lispgram 0.10.0 → 0.10.3

package/README.md

@@ -118,10 +118,11 @@ npm install lispgram
 <script type="module">
   import lispgram from "lispgram";
   lispgram.initialize({
-  startOnLoad: true,
-  showArrowGlyphs: true,
-  clickToFocus: true
-});
+    startOnLoad: true,
+    showArrowGlyphs: true,
+    clickToFocus: true,
+    zoom: true
+  });
 </script>
 ```
 
@@ -226,6 +227,8 @@ import { render, renderElement, initialize, createDiagramSvg } from "lispgram/la
 
 `render(target, source, options?)` renders Lispgram or NCF into a DOM target. `renderElement(sourceElement, options?)` renders one source element. `initialize(options?)` auto-renders matching elements such as `<pre class="lispgram">`. `createDiagramSvg(doc, options?)` renders an already-normalized NCF document into an SVG element.
 
+`options.zoom` is a boolean that controls the built-in Shift navigation tools. The default is `true`, which enables Shift + A + click zoom-to-target, cursor-centered Shift + wheel zoom, and Shift + drag panning. Shift + A + click fits containers to about 80% of the viewport. Ordinary nodes zoom until the node height is about 8% of the view height. Arrows zoom to their arrow glyph/label area at about 2% of the view height. Use `zoom: false`, or `data-lispgram-zoom="false"` on auto-rendered `<pre>` blocks, to disable all built-in zoom and panning behavior.
+
 ### Interaction entry point
 
 ```js
@@ -286,6 +289,8 @@ When `clickToFocus` is enabled, clicking a node, compound/container, or arrow fo
 
 Click hit-testing uses a transparent interaction layer above the rendered diagram. Ordinary nodes are given priority over arrows, arrows over container interiors, and deeper containers over their ancestors. This keeps large ancestor containers clickable without letting them steal clicks from nested containers such as `BuildSystem`, `ExternalDependencies`, or `GuileBinding`.
 
+The examples use `zoom: true`, which is also the default. It enables Shift + A + click zoom-to-target, Shift-wheel cursor zoom, and Shift-drag panning. Containers fit to roughly 80% of the viewport; ordinary nodes fit to about 8% of the view height; arrows fit to the arrow glyph/label area at about 2% of the view height. Pass `zoom: false` to disable built-in zoom and pan behavior.
+
 ## Demo
 
 go to repo root directory
@@ -308,10 +313,11 @@ navigate to examples/basic.html in browser
 </pre>
 <script type="module">
   import lispgram from "https://unpkg.com/lispgram@latest/dist/index.js";
-    lispgram.initialize({
+  lispgram.initialize({
     startOnLoad: true,
     showArrowGlyphs: true,
     clickToFocus: true,
+    zoom: true,
     arrowGlyphRadius: 5.75
   });
 </script>

package/dist/index.js

@@ -4772,7 +4772,7 @@ function renderLispgramRoute(svg, route, options) {
 }
 
 function renderLispgramHitLayer(svg, result, options = {}) {
-  if (options.clickToFocus === false) return;
+  if (options.clickToFocus === false && !zoomEnabled(options)) return;
   const layer = svgEl('g', { class: 'lispgram-hit-layer', 'aria-hidden': 'true' });
 
   // Container hit regions are separate from the visible paint order.  They are
@@ -4888,6 +4888,330 @@ function routeTouchesFocus(route, focus) {
   return endpointTouches(route.fromEndpoint, focus.id, focus.type) || endpointTouches(route.toEndpoint, focus.id, focus.type);
 }
 
+function zoomEnabled(options = {}) {
+  return options.zoom !== false;
+}
+
+const lispgramZoomKeyState = new WeakMap();
+
+function normalizeKeyboardKey(event) {
+  return String(event?.key || event?.code || '').toLowerCase();
+}
+
+function eventHasZoomClickKey(svg, event) {
+  if (event?.aKey === true) return true;
+  const key = normalizeKeyboardKey(event);
+  if (key === 'a' || key === 'keya') return true;
+  return !!lispgramZoomKeyState.get(svg)?.aDown;
+}
+
+function isZoomClickEvent(svg, event) {
+  return !!event?.shiftKey && eventHasZoomClickKey(svg, event);
+}
+
+function parseViewBox(svg) {
+  const raw = svg?.getAttribute?.('viewBox') || '';
+  const nums = raw.trim().split(/[\s,]+/).map(Number).filter(Number.isFinite);
+  if (nums.length >= 4) return { x: nums[0], y: nums[1], w: nums[2], h: nums[3] };
+  return null;
+}
+
+function writeViewBox(svg, vb) {
+  if (!svg || !vb) return;
+  svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+}
+
+function svgDisplayAspect(svg, fallbackViewBox) {
+  const attrW = Number(svg?.getAttribute?.('width'));
+  const attrH = Number(svg?.getAttribute?.('height'));
+  if (Number.isFinite(attrW) && attrW > 0 && Number.isFinite(attrH) && attrH > 0) return attrW / attrH;
+  const rect = typeof svg?.getBoundingClientRect === 'function' ? svg.getBoundingClientRect() : null;
+  if (rect?.width > 0 && rect?.height > 0) return rect.width / rect.height;
+  return fallbackViewBox?.w && fallbackViewBox?.h ? fallbackViewBox.w / fallbackViewBox.h : 1;
+}
+
+function svgPointFromEvent(svg, event, fallbackViewBox) {
+  const vb = parseViewBox(svg) || fallbackViewBox;
+  if (!vb) return null;
+  const rect = typeof svg?.getBoundingClientRect === 'function' ? svg.getBoundingClientRect() : null;
+  if (rect?.width > 0 && rect?.height > 0 && Number.isFinite(event?.clientX) && Number.isFinite(event?.clientY)) {
+    return {
+      x: vb.x + ((event.clientX - rect.left) / rect.width) * vb.w,
+      y: vb.y + ((event.clientY - rect.top) / rect.height) * vb.h
+    };
+  }
+  return { x: vb.x + vb.w / 2, y: vb.y + vb.h / 2 };
+}
+
+function zoomViewBoxAt(svg, pivot, factor, originalViewBox, options = {}) {
+  const vb = parseViewBox(svg) || originalViewBox;
+  if (!vb || !pivot || !Number.isFinite(factor) || factor <= 0) return null;
+  const minScale = Number.isFinite(Number(options.zoomMinScale)) ? Number(options.zoomMinScale) : 0.08;
+  const maxScale = Number.isFinite(Number(options.zoomMaxScale)) ? Number(options.zoomMaxScale) : 6;
+  const base = originalViewBox || vb;
+  let nextW = vb.w * factor;
+  let nextH = vb.h * factor;
+  nextW = Math.max(base.w * minScale, Math.min(base.w * maxScale, nextW));
+  nextH = Math.max(base.h * minScale, Math.min(base.h * maxScale, nextH));
+  const actualX = nextW / vb.w;
+  const actualY = nextH / vb.h;
+  const next = {
+    x: pivot.x - (pivot.x - vb.x) * actualX,
+    y: pivot.y - (pivot.y - vb.y) * actualY,
+    w: nextW,
+    h: nextH
+  };
+  writeViewBox(svg, next);
+  return next;
+}
+
+function viewBoxForBox(svg, box, originalViewBox, options = {}) {
+  if (!box || !originalViewBox) return null;
+  const ratioRaw = Number(options.zoomFitRatio ?? options.containerZoomFitRatio ?? 0.8);
+  const fitRatio = Number.isFinite(ratioRaw) && ratioRaw > 0 && ratioRaw < 1 ? ratioRaw : 0.8;
+  const aspect = svgDisplayAspect(svg, originalViewBox) || 1;
+  const minW = Number(options.containerZoomMinWidth ?? 160);
+  const minH = Number(options.containerZoomMinHeight ?? 120);
+  let w = Math.max(box.w / fitRatio, (box.h / fitRatio) * aspect, minW);
+  let h = w / aspect;
+  if (h < Math.max(box.h / fitRatio, minH)) {
+    h = Math.max(box.h / fitRatio, minH);
+    w = h * aspect;
+  }
+  const maxW = originalViewBox.w * (Number(options.containerZoomMaxScale ?? 1.05) || 1.05);
+  const maxH = originalViewBox.h * (Number(options.containerZoomMaxScale ?? 1.05) || 1.05);
+  if (w > maxW || h > maxH) {
+    const scale = Math.max(w / maxW, h / maxH);
+    w /= scale;
+    h /= scale;
+  }
+  return { x: box.cx - w / 2, y: box.cy - h / 2, w, h };
+}
+
+function finiteBounds(points) {
+  const pts = (points || []).filter((p) => p && Number.isFinite(p.x) && Number.isFinite(p.y));
+  if (!pts.length) return null;
+  let left = Infinity;
+  let right = -Infinity;
+  let top = Infinity;
+  let bottom = -Infinity;
+  for (const p of pts) {
+    left = Math.min(left, p.x);
+    right = Math.max(right, p.x);
+    top = Math.min(top, p.y);
+    bottom = Math.max(bottom, p.y);
+  }
+  return { left, right, top, bottom, w: right - left, h: bottom - top, cx: (left + right) / 2, cy: (top + bottom) / 2 };
+}
+
+function routeZoomBounds(route, options = {}) {
+  const mid = route?.anchors?.label || route?.anchors?.mid || pointAlongPolyline(route?.points || [], 0.5);
+  const glyphRadius = Number.isFinite(Number(options.arrowGlyphRadius)) ? Number(options.arrowGlyphRadius) : 5;
+  const glyphDiameter = Math.max(10, glyphRadius * 2);
+  const routeBounds = finiteBounds(route?.points || []);
+  if (!mid) return routeBounds;
+  const desired = Math.max(glyphDiameter, Number(options.arrowZoomTargetSize || 0) || 0);
+  const half = desired / 2;
+  return {
+    left: mid.x - half,
+    right: mid.x + half,
+    top: mid.y - half,
+    bottom: mid.y + half,
+    w: desired,
+    h: desired,
+    cx: mid.x,
+    cy: mid.y,
+    routeBounds
+  };
+}
+
+function viewBoxForSmallBounds(svg, bounds, originalViewBox, options = {}) {
+  if (!bounds || !originalViewBox) return null;
+  const aspect = svgDisplayAspect(svg, originalViewBox) || 1;
+  const fractionRaw = Number(options.zoomTargetHeightFraction ?? options.smallZoomHeightFraction ?? 0.08);
+  const fraction = Number.isFinite(fractionRaw) && fractionRaw > 0 && fractionRaw < 1 ? fractionRaw : 0.08;
+  const minTargetH = Number.isFinite(Number(options.smallZoomMinTargetHeight)) ? Number(options.smallZoomMinTargetHeight) : 10;
+  const targetH = Math.max(bounds.h || 0, minTargetH);
+  let h = targetH / fraction;
+  let w = h * aspect;
+  const minW = Number(options.smallZoomMinWidth ?? 120);
+  const minH = Number(options.smallZoomMinHeight ?? 90);
+  if (w < minW) { w = minW; h = w / aspect; }
+  if (h < minH) { h = minH; w = h * aspect; }
+  return { x: bounds.cx - w / 2, y: bounds.cy - h / 2, w, h };
+}
+
+function viewBoxForZoomTarget(svg, target, result, originalViewBox, options = {}) {
+  if (!target || !originalViewBox) return null;
+  if (target.type === 'node') {
+    const box = result.boxes?.get?.(target.id);
+    if (!box) return null;
+    if (box.kind === 'container') return viewBoxForBox(svg, box, originalViewBox, options);
+    return viewBoxForSmallBounds(svg, box, originalViewBox, options);
+  }
+  if (target.type === 'edge') {
+    const route = result.routes?.get?.(target.id);
+    const edgeOptions = {
+      ...options,
+      zoomTargetHeightFraction: options.arrowZoomHeightFraction ?? options.edgeZoomHeightFraction ?? 0.02,
+      smallZoomMinTargetHeight: options.arrowZoomMinTargetHeight ?? options.edgeZoomMinTargetHeight ?? 10
+    };
+    return viewBoxForSmallBounds(svg, routeZoomBounds(route, edgeOptions), originalViewBox, edgeOptions);
+  }
+  return null;
+}
+
+function enableLispgramZoom(svg, result, options = {}) {
+  if (!svg || !result || !zoomEnabled(options)) return;
+  const originalViewBox = parseViewBox(svg) || result.viewBox || null;
+  if (!originalViewBox) return;
+  let currentViewBox = { ...originalViewBox };
+  const animationMs = Number.isFinite(Number(options.zoomAnimationMs)) ? Number(options.zoomAnimationMs) : 160;
+
+  function setViewBox(vb) {
+    if (!vb) return null;
+    currentViewBox = { ...vb };
+    if (svg.style && animationMs > 0) svg.style.transition = `viewBox ${animationMs}ms ease`;
+    writeViewBox(svg, currentViewBox);
+    return currentViewBox;
+  }
+
+  function zoomToTarget(target) {
+    return setViewBox(viewBoxForZoomTarget(svg, target, result, originalViewBox, options));
+  }
+
+  function zoomToBox(id) {
+    return zoomToTarget({ type: 'node', id });
+  }
+
+  function zoomToEdge(id) {
+    return zoomToTarget({ type: 'edge', id });
+  }
+
+  function reset() {
+    return setViewBox(originalViewBox);
+  }
+
+  let suppressNextShiftClick = false;
+  const keyState = { aDown: false };
+  lispgramZoomKeyState.set(svg, keyState);
+
+  function updateZoomKeyState(event, value) {
+    const key = normalizeKeyboardKey(event);
+    if (key === 'a' || key === 'keya') keyState.aDown = value;
+  }
+
+  const keyTargets = [];
+  const ownerDocument = svg.ownerDocument || (typeof document !== 'undefined' ? document : null);
+  if (ownerDocument?.defaultView?.addEventListener) keyTargets.push(ownerDocument.defaultView);
+  if (ownerDocument?.addEventListener) keyTargets.push(ownerDocument);
+  for (const target of keyTargets) {
+    target.addEventListener('keydown', (event) => updateZoomKeyState(event, true));
+    target.addEventListener('keyup', (event) => updateZoomKeyState(event, false));
+    target.addEventListener('blur', () => { keyState.aDown = false; });
+  }
+
+  if (typeof svg.addEventListener === 'function') {
+    svg.addEventListener('wheel', (event) => {
+      if (!event?.shiftKey) return;
+      if (typeof event.preventDefault === 'function') event.preventDefault();
+      const scale = Number.isFinite(Number(options.zoomWheelScale)) ? Number(options.zoomWheelScale) : 1.05;
+      const delta = Number(event.deltaY || 0);
+      const factor = delta < 0 ? 1 / scale : scale;
+      const pivot = svgPointFromEvent(svg, event, currentViewBox);
+      currentViewBox = zoomViewBoxAt(svg, pivot, factor, originalViewBox, options) || currentViewBox;
+    }, { passive: false });
+
+    let dragState = null;
+    const dragThreshold = Number.isFinite(Number(options.zoomDragThreshold)) ? Number(options.zoomDragThreshold) : 3;
+
+    function updateDrag(event) {
+      if (!dragState) return;
+      const rect = typeof svg.getBoundingClientRect === 'function' ? svg.getBoundingClientRect() : null;
+      if (!rect?.width || !rect?.height) return;
+      const dx = Number(event.clientX) - dragState.startClientX;
+      const dy = Number(event.clientY) - dragState.startClientY;
+      if (!dragState.moved && Math.hypot(dx, dy) >= dragThreshold) dragState.moved = true;
+      if (typeof event.preventDefault === 'function') event.preventDefault();
+      const next = {
+        x: dragState.startViewBox.x - dx / rect.width * dragState.startViewBox.w,
+        y: dragState.startViewBox.y - dy / rect.height * dragState.startViewBox.h,
+        w: dragState.startViewBox.w,
+        h: dragState.startViewBox.h
+      };
+      currentViewBox = next;
+      writeViewBox(svg, currentViewBox);
+    }
+
+    function endDrag(event) {
+      if (!dragState) return;
+      if (dragState.moved) {
+        suppressNextShiftClick = true;
+        if (typeof event?.preventDefault === 'function') event.preventDefault();
+      }
+      if (dragState.pointerId != null && typeof svg.releasePointerCapture === 'function') {
+        try { svg.releasePointerCapture(dragState.pointerId); } catch {}
+      }
+      dragState = null;
+      if (svg.style) svg.style.cursor = '';
+      setTimeout(() => { suppressNextShiftClick = false; }, 0);
+    }
+
+    if (typeof svg.addEventListener === 'function') {
+      svg.addEventListener('pointerdown', (event) => {
+        if (!event?.shiftKey) return;
+        if (isZoomClickEvent(svg, event)) return;
+        if (event.button != null && event.button !== 0) return;
+        const start = parseViewBox(svg) || currentViewBox;
+        if (!start) return;
+        dragState = {
+          pointerId: event.pointerId,
+          startClientX: Number(event.clientX),
+          startClientY: Number(event.clientY),
+          startViewBox: { ...start },
+          moved: false
+        };
+        if (typeof svg.setPointerCapture === 'function' && event.pointerId != null) {
+          try { svg.setPointerCapture(event.pointerId); } catch {}
+        }
+        if (svg.style) svg.style.cursor = 'grabbing';
+        if (typeof event.preventDefault === 'function') event.preventDefault();
+      }, { passive: false });
+      svg.addEventListener('pointermove', updateDrag, { passive: false });
+      svg.addEventListener('pointerup', endDrag, { passive: false });
+      svg.addEventListener('pointercancel', endDrag, { passive: false });
+    }
+  }
+
+  {
+    const hitboxes = [];
+    walkSvgElements(svg, (node) => {
+      if (typeof node.getAttribute !== 'function') return;
+      const cls = node.getAttribute('class');
+      if (cls === 'lispgram-compound-hitbox' || cls === 'lispgram-node-hitbox') {
+        const id = node.getAttribute('data-node-id');
+        if (result.boxes?.has?.(id)) hitboxes.push([node, { type: 'node', id }]);
+      } else if (cls === 'lispgram-edge-hitbox') {
+        const id = node.getAttribute('data-edge-id');
+        if (result.routes?.has?.(id)) hitboxes.push([node, { type: 'edge', id }]);
+      }
+    });
+    for (const [el, target] of hitboxes) {
+      if (typeof el.addEventListener !== 'function') continue;
+      el.addEventListener('click', (event) => {
+        if (!isZoomClickEvent(svg, event)) return;
+        if (suppressNextShiftClick) return;
+        if (typeof event.preventDefault === 'function') event.preventDefault();
+        if (typeof event.stopPropagation === 'function') event.stopPropagation();
+        if (typeof event.stopImmediatePropagation === 'function') event.stopImmediatePropagation();
+        zoomToTarget(target);
+      });
+    }
+  }
+
+  svg.__lispgramZoom = { enabled: true, originalViewBox, get viewBox() { return currentViewBox; }, reset, zoomToBox, zoomToEdge, zoomToTarget };
+}
+
 function enableLispgramClickFocus(svg, result, options = {}) {
   if (!svg || !result || options.clickToFocus === false) return;
   const dimOpacity = Number.isFinite(Number(options.focusDimOpacity)) ? Number(options.focusDimOpacity) : 0.12;
@@ -4960,6 +5284,7 @@ function enableLispgramClickFocus(svg, result, options = {}) {
       if (typeof el.addEventListener !== 'function') continue;
       if (el.style) el.style.cursor = 'pointer';
       el.addEventListener('click', (event) => {
+        if (zoomEnabled(options) && event?.shiftKey && result.boxes?.has?.(id)) return;
         stop(event);
         const next = { type: 'node', id };
         applyFocus(sameFocus(currentFocus, next) ? null : next);
@@ -4972,6 +5297,7 @@ function enableLispgramClickFocus(svg, result, options = {}) {
       if (typeof el.addEventListener !== 'function') continue;
       if (el.style) el.style.cursor = 'pointer';
       el.addEventListener('click', (event) => {
+        if (zoomEnabled(options) && event?.shiftKey && result.routes?.has?.(id)) return;
         stop(event);
         const next = { type: 'edge', id };
         applyFocus(sameFocus(currentFocus, next) ? null : next);
@@ -4999,6 +5325,7 @@ function createLispgramConstraintSvg(result, options = {}) {
   for (const route of result.routes.values()) renderLispgramRoute(svg, route, options);
   renderLispgramHitLayer(svg, result, options);
   enableLispgramClickFocus(svg, result, options);
+  enableLispgramZoom(svg, result, options);
   return svg;
 }
 
@@ -5207,6 +5534,7 @@ function elementRenderOptions(sourceElement, options = {}) {
     ...options,
     showArrowGlyphs: parseBooleanOption(data.lispgramArrowGlyphs, options.showArrowGlyphs ?? false),
     clickToFocus: parseBooleanOption(data.lispgramClickFocus, options.clickToFocus ?? true),
+    zoom: parseBooleanOption(data.lispgramZoom, options.zoom ?? true),
     arrowGlyphRadius: parseNumericOption(data.lispgramArrowGlyphRadius, options.arrowGlyphRadius),
     diagramId: data.lispgramDiagram || data.diagramId || options.diagramId || options.name || options.id || sourceElement?.id || undefined
   };
@@ -5277,6 +5605,7 @@ function initialize(options = {}) {
     showNCF = false,
     showArrowGlyphs = false,
     clickToFocus = true,
+    zoom = true,
     arrowGlyphRadius = 5.75,
     height,
     width,
@@ -5288,7 +5617,7 @@ function initialize(options = {}) {
     for (const element of elements) {
       if (element.dataset.lispgramMounted === 'true') continue;
       try {
-        renderElement(element, { showNCF, showArrowGlyphs, clickToFocus, arrowGlyphRadius, height, width, diagramId });
+        renderElement(element, { showNCF, showArrowGlyphs, clickToFocus, zoom, arrowGlyphRadius, height, width, diagramId });
         element.dataset.lispgramMounted = 'true';
       } catch {
         element.dataset.lispgramMounted = 'error';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lispgram",
-  "version": "0.10.0",
+  "version": "0.10.3",
   "description": "A small public Lispgram surface compiler, constraint-layout SVG renderer, and interaction API.",
   "type": "module",
   "main": "./dist/index.js",