@shawcx/avispa 1.0.0 → 2.1.0

package/README.md

@@ -1,11 +1,124 @@
 Avispa
 ======
 
-Javascript Graph Layout and Interaction
+Draw node/link graphs in SVG and interact with them: drag nodes and groups, pan,
+zoom, bend links, and resize, nest, and collapse groups, with mouse, pen, or touch.
+Items are Backbone views, and an optional WebSocket feed keeps a graph live.
 
-Avispa (spanish for wasp) is a visualization framework. It is intended to be a
-general purpose Javascript library for rendering graphs.
+Avispa is Spanish for wasp.
 
-Depends on jQuery, Underscore.js, and Backbone.js
+Demo at [https://shawcx.github.io/avispa/](https://shawcx.github.io/avispa/)
 
-Demo at [http://shawcx.github.io/avispa/](http://shawcx.github.io/avispa/)
+Install
+-------
+
+```sh
+npm install @shawcx/avispa jquery underscore backbone
+```
+
+jQuery (3 or 4), Underscore, and Backbone are peer dependencies, so your app
+supplies one copy of each. The library is CommonJS (`js/Avispa.js`), meant to be
+bundled with browserify, webpack, esbuild, or similar. The theme is
+`css/Avispa.css`, or `@use` `scss/Avispa.scss` from your own Sass.
+
+Page setup
+----------
+
+Avispa draws into an SVG on your page, which needs these layers, and an `#Arrow`
+marker for the link arrowheads:
+
+```html
+<svg class="avispa">
+  <defs>
+    <marker id="Arrow" viewBox="0 0 10 10" refX="7" refY="5"
+            markerWidth="4" markerHeight="4" orient="auto">
+      <path d="M 1 1 L 9 5 L 1 9 z" />
+    </marker>
+  </defs>
+  <g class="pan">
+    <g class="zoom">
+      <g class="groups"></g>
+      <g class="links"></g>
+      <g class="objects"></g>
+      <g class="labels"></g>
+    </g>
+  </g>
+</svg>
+```
+
+Usage
+-----
+
+Each item takes a `Position` model; moving an item means setting its position, and
+the view redraws. A child's `x` and `y` are relative to its parent group.
+
+```js
+const $      = require('jquery')
+const Avispa = require('@shawcx/avispa')
+
+$(() => {
+    const graph = new Avispa.Avispa({ el: $('svg.avispa') })
+
+    const group = new Avispa.Group({
+        position: new Avispa.Position({ x: -200, y: -75, w: 200, h: 150 }),
+    })
+    graph.$groups.append(group.$el)
+
+    const a = new Avispa.Node({
+        label:    'A',
+        parent:   group,
+        position: new Avispa.Position({ x: 60, y: 75, radius: 30 }),
+    })
+    const b = new Avispa.Node({
+        label:    'B',
+        position: new Avispa.Position({ x: 150, y: 0, radius: 30 }),
+    })
+    graph.$objects.append(a.$el, b.$el)
+
+    new Avispa.Link({ parent: graph, left: a, right: b })
+
+    // a.position.set({ x: 80 }) moves A and its link
+})
+```
+
+On screen:
+
+- Drag the background to pan, scroll or pinch to zoom in on the spot under the
+  pointer or between your fingers, and middle-click to recenter.
+- Drag a node or group to move it; a group's children come along. A node stays
+  inside its group, and a nested group dragged past its parent's edge grows it.
+- Drag a group's bottom-right corner to resize it, down to what its contents need.
+- Drag a link to bend it; shift-click it to straighten it.
+
+In code, `group.Collapse()`, `Expand()`, and `ToggleCollapse()` shrink a group to
+its title bar and hide what's inside, and `item.remove()` takes an item off the
+graph (remove its links yourself).
+
+To customize, subclass `Avispa`, `Group`, `Node`, and `Link`, and override
+`initialize` (calling `super`), `render`, and the `LeftClick`, `MiddleClick`,
+`RightClick`, and `OnContextMenu` hooks. [`example/src/example.js`](example/src/example.js)
+does this, adding a title to each group that collapses it on double-click.
+
+### WebSocket
+
+```js
+class Graph extends Avispa.Avispa {
+    OnMessage(msg) {
+        // each JSON message from ws(s)://<page host>/ws
+    }
+}
+
+const graph = new Graph({ el: $('svg.avispa'), socket: 'ws' })
+graph.socket.send({ hello: 'world' })
+```
+
+The socket reconnects with backoff, keeps the connection alive with pings, and
+queues anything sent before it opens. Pass an options object instead of a path
+for an explicit `url` or your own `onopen` / `onclose` / `onmessage` callbacks.
+
+Development
+-----------
+
+- `npm run example` builds the demo in `example/` and opens it in a browser.
+- `npm test` runs the Playwright tests in Google Chrome.
+- `npm run build` compiles `scss/Avispa.scss` to `css/Avispa.css`.

package/css/Avispa.css

@@ -9,9 +9,14 @@ g.group rect.hover {
   stroke: #333;
   stroke-width: 2px;
 }
+g.group rect.handle {
+  cursor: nwse-resize;
+  fill: #999;
+  stroke: none;
+}
 g.group text {
   cursor: pointer;
-  font: bold 8pt "Andale Mono", AndaleMono, monospace;
+  font: bold 10pt "Andale Mono", AndaleMono, monospace;
   fill: #000;
   text-anchor: left;
 }

package/css/Avispa.css.map

@@ -1 +1 @@
-{"version":3,"sourceRoot":"","sources":["../scss/Avispa.scss"],"names":[],"mappings":"AAMI;EACI;EACA;EACA;EACA;EACA;;AAGJ;EACI;EACA;;AAGJ;EACI;EACA;EACA;EACA;;;AAKJ;EACI;EACA;EACA;EACA;;AAGJ;EACI;EACA;;AAGJ;EACI;EACA;EACA;EACA;;;AAKJ;EACI;EACA;EACA;EACA;;AAGJ;EACI;EAEA;EACA;EACA;EACA;EACA;;AAGJ;EACI;EACA;EACA;EACA","file":"Avispa.css"}
+{"version":3,"sourceRoot":"","sources":["../scss/Avispa.scss"],"names":[],"mappings":"AAMI;EACI;EACA;EACA;EACA;EACA;;AAGJ;EACI;EACA;;AAGJ;EACI;EACA;EACA;;AAGJ;EACI;EACA;EACA;EACA;;;AAKJ;EACI;EACA;EACA;EACA;;AAGJ;EACI;EACA;;AAGJ;EACI;EACA;EACA;EACA;;;AAKJ;EACI;EACA;EACA;EACA;;AAGJ;EACI;EAEA;EACA;EACA;EACA;EACA;;AAGJ;EACI;EACA;EACA;EACA","file":"Avispa.css"}

package/js/Avispa.js

@@ -3,47 +3,38 @@
 const _        = require('underscore')
 const Backbone = require('backbone')
 
-const { Position }          = require('./Types.js')
-const { cancelEvent, $SVG } = require('./Utils.js')
+const { Position }                     = require('./Types.js')
+const { cancelEvent, $SVG, normalizeWheel } = require('./Utils.js')
 
 const context      = require('./Context.js')
 const Group        = require('./Group.js')
 const Node         = require('./Node.js')
 const Link         = require('./Link.js')
-
-let normalizeWheel = function(event) {
-    if (event.wheelDelta) {
-        return event.wheelDelta / 120
-    }
-    if (event.detail) {
-        return event.detail / -3
-    }
-    return 0
-}
-
-
-const $SVG = function(name) {
-    return $(document.createElementNS('http://www.w3.org/2000/svg', name))
-}
-
+const Socket       = require('./Socket.js')
 
 class Avispa extends Backbone.View {
+    static TOUCH_EVENTS = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']
+
     events() {
         return {
-            'mousedown.avispa'      : 'OnMouseDown',
-            'mousemove.avispa'      : 'OnMouseMove',
-            'mouseup.avispa'        : 'OnMouseUp',
-            'mousewheel.avispa'     : 'OnMouseWheel',
-            'DOMMouseScroll.avispa' : 'OnMouseWheel',
-            'contextmenu.avispa'    : 'OnContextMenu',
+            'pointerdown.avispa'   : 'OnMouseDown',
+            'pointermove.avispa'   : 'OnMouseMove',
+            'pointerup.avispa'     : 'OnMouseUp',
+            'pointercancel.avispa' : 'OnPointerCancel',
+            'wheel.avispa'         : 'OnMouseWheel',
+            'contextmenu.avispa'   : 'OnContextMenu',
             }
     }
 
     initialize(options) {
         context.a = this
 
+        // the surface handles its own drags: keep touch from panning the page
+        // and drags from selecting text
+        this.$el.css({'touch-action': 'none', 'user-select': 'none'})
+
         _.bindAll(this, 'render',
-            'OnMouseDown', 'OnMouseMove', 'OnMouseUp', 'OnMouseWheel', 'OnContextMenu')
+            'OnMouseDown', 'OnMouseMove', 'OnMouseUp', 'OnMouseWheel', 'OnContextMenu', 'OnTouch')
 
         this.scale    = 1.0
         this.links    = {}
@@ -51,6 +42,15 @@ class Avispa extends Backbone.View {
         this.dragItem = null
         this.arrow    = null
 
+        // touch points by pointerId, as client [x, y], and the pinch two of
+        // them make. Watched in the capture phase, since items stop pointerdown
+        // from bubbling up to the surface
+        this.touches  = new Map()
+        this.pinch    = null
+        for (const type of Avispa.TOUCH_EVENTS) {
+            this.el.addEventListener(type, this.OnTouch, true)
+        }
+
         this.position = {
             x: 0,
             y: 0
@@ -72,10 +72,35 @@ class Avispa extends Backbone.View {
         this.$objects = this.$el.find('g.objects')
         this.$labels  = this.$el.find('g.labels')
 
-        this.$pan.x = parseInt(window.innerWidth  / 2)
-        this.$pan.y = parseInt(window.innerHeight / 2)
+        this.$pan.x = 0
+        this.$pan.y = 0
+
+        this.Center()
+
+        // opt-in WebSocket transport: `socket` may be a path string or a
+        // Socket options object. Incoming messages are routed to OnMessage
+        // unless the caller supplies its own onmessage handler.
+        if (options && options.socket) {
+            let socketOptions = (typeof options.socket === 'string')
+                ? { path: options.socket }
+                : Object.assign({}, options.socket)
+
+            if (!socketOptions.onmessage) {
+                socketOptions.onmessage = (msg) => this.OnMessage(msg)
+            }
+
+            this.socket = new Socket(socketOptions)
+        }
+    }
 
-        this.Pan(0,0)
+    remove() {
+        if (this.socket) {
+            this.socket.close()
+        }
+        for (const type of Avispa.TOUCH_EVENTS) {
+            this.el.removeEventListener(type, this.OnTouch, true)
+        }
+        return super.remove()
     }
 
     Pan(dx, dy) {
@@ -94,26 +119,66 @@ class Avispa extends Backbone.View {
         return this
     }
 
-    Zoom(delta) {
-        let scale = (delta == 0) ? 1.0 : this.scale + delta * this.zoom.step
-        if (scale >= this.zoom.min || scale <= this.zoom.max) {
-            this.Scale(scale)
+    // put the surface's origin in the middle of the SVG
+    Center() {
+        let [x, y] = this.Middle()
+        return this.Pan(parseInt(x) - this.$pan.x, parseInt(y) - this.$pan.y)
+    }
+
+    // zoom by `delta` steps (0 resets to 1), keeping what's drawn at `at`
+    // where it is (see ZoomTo)
+    Zoom(delta, at) {
+        return this.ZoomTo((delta == 0) ? 1.0 : this.scale + delta * this.zoom.step, at)
+    }
+
+    // zoom to `scale` within the limits, keeping what's drawn at `at` (an
+    // [x, y] from Local) where it is; without `at`, the origin stays put
+    ZoomTo(scale, at) {
+        scale = Math.min(this.zoom.max, Math.max(this.zoom.min, scale))
+        if (!at) {
+            return this.Scale(scale)
         }
-        return this
+        let point = this.Surface(at)
+        this.Scale(scale)
+        return this.PanTo(point, at)
     }
 
-    Point(event) {
-        // translates the client x,y into the surface x,y
+    // pan so the surface point `point` is drawn at `at` (an [x, y] from Local)
+    PanTo(point, at) {
+        return this.Pan(
+            at[0] - point[0] * this.scale - this.$pan.x,
+            at[1] - point[1] * this.scale - this.$pan.y)
+    }
+
+    // translates a client x,y into the SVG's own coordinates, before the pan
+    // and zoom; an SVG that isn't laid out (display: none) has no transform
+    Local(x, y) {
+        let ctm = this.el.getScreenCTM()
+        if (!ctm) {
+            return [x, y]
+        }
         let point = this.el.createSVGPoint()
-        point.x = event.clientX
-        point.y = event.clientY
-        point = point.matrixTransform(this.el.getScreenCTM().inverse())
+        point.x = x
+        point.y = y
+        point = point.matrixTransform(ctm.inverse())
+        return [point.x, point.y]
+    }
 
-        // account for the current pan and scale
-        point.x = parseInt((point.x - this.$pan.x) / this.scale)
-        point.y = parseInt((point.y - this.$pan.y) / this.scale)
+    // the middle of the SVG, from Local
+    Middle() {
+        let box = this.el.getBoundingClientRect()
+        return this.Local(box.left + box.width / 2, box.top + box.height / 2)
+    }
 
-        return [point.x, point.y]
+    // the surface point drawn at `at` (an [x, y] from Local)
+    Surface(at) {
+        return [(at[0] - this.$pan.x) / this.scale, (at[1] - this.$pan.y) / this.scale]
+    }
+
+    Point(event) {
+        // translates the client x,y into the surface x,y
+        let [x, y] = this.Surface(this.Local(event.clientX, event.clientY))
+        return [parseInt(x), parseInt(y)]
     }
 
     OnMouseDown(event) {
@@ -123,14 +188,14 @@ class Avispa extends Backbone.View {
             return cancelEvent(event)
         }
 
-        switch (event.which) {
-            case 1:
+        switch (event.button) {
+            case 0:
                 this.LeftDown(event)
                 break
-            case 2:
+            case 1:
                 this.MiddleDown(event)
                 break
-            case 3:
+            case 2:
                 if (this.RightDown) {
                     this.RightDown(event)
                 }
@@ -146,12 +211,19 @@ class Avispa extends Backbone.View {
     }
 
     MiddleDown(event) {
-        this.Pan(-this.$pan.x + window.innerWidth / 2, -this.$pan.y + window.innerHeight / 2)
+        this.Center()
         this.Zoom(0)
         //this.$('#zoomslider').slider('option', 'value', 1)
     }
 
     OnMouseMove(event) {
+        // once a drag is moving, capture its pointer so the drag carries on
+        // outside the SVG and its release comes back here. Not on pointerdown:
+        // a plain click or double-click would then go to the SVG, not the item
+        if ((this.offset || this.dragItem) && !this.el.hasPointerCapture(event.pointerId)) {
+            this.el.setPointerCapture(event.pointerId)
+        }
+
         // drag the entire scene around
         if (this.offset) {
             this.Pan(event.clientX - this.offset[0], event.clientY - this.offset[1])
@@ -174,33 +246,34 @@ class Avispa extends Backbone.View {
         this.offset = null
 
         if (this.dragItem) {
+            // click hooks are optional on drag items (Link has no Middle/RightClick)
             if (this.dragItem.jitter < 3) {
-                switch (event.which) {
+                switch (event.button) {
+                    case 0:
+                        if (this.dragItem.LeftClick) this.dragItem.LeftClick(event)
+                        break
                     case 1:
-                        this.dragItem.LeftClick(event)
+                        if (this.dragItem.MiddleClick) this.dragItem.MiddleClick(event)
                         break
                     case 2:
-                        this.dragItem.MiddleClick(event)
-                        break
-                    case 3:
-                        this.dragItem.RightClick(event)
+                        if (this.dragItem.RightClick) this.dragItem.RightClick(event)
                         break
                 }
             }
-            else if(this.dragItem.MouseUp) {
+            if (this.dragItem.MouseUp) {
                 this.dragItem.MouseUp(event)
             }
             this.dragItem = null
         }
         else {
-            switch (event.which) {
-                case 1:
+            switch (event.button) {
+                case 0:
                     this.LeftClick(event)
                     break
-                case 2:
+                case 1:
                     this.MiddleClick(event)
                     break
-                case 3:
+                case 2:
                     this.RightClick(event)
                     break
             }
@@ -209,8 +282,65 @@ class Avispa extends Backbone.View {
         return cancelEvent(event)
     }
 
+    OnPointerCancel(event) {
+        // the browser took the pointer over: drop any pan or drag in progress
+        this.offset   = null
+        this.dragItem = null
+    }
+
+    // A second finger turns whatever the first one started into a pinch,
+    // which zooms by how far apart the fingers move and pans with their
+    // midpoint. It lasts until every finger is up, and until then the touches
+    // go no further than here: lifting the last finger isn't a click.
+    OnTouch(event) {
+        // only touches that started here: one whose release never comes would
+        // turn every later single touch into a pinch
+        if (event.pointerType !== 'touch' ||
+            (event.type !== 'pointerdown' && !this.touches.has(event.pointerId))) {
+            return
+        }
+
+        if (event.type === 'pointerup' || event.type === 'pointercancel') {
+            this.touches.delete(event.pointerId)
+        }
+        else {
+            this.touches.set(event.pointerId, [event.clientX, event.clientY])
+        }
+
+        let [a, b] = this.touches.values()
+        let middle = () => this.Local((a[0] + b[0]) / 2, (a[1] + b[1]) / 2)
+
+        if (event.type !== 'pointermove' && this.touches.size >= 2) {
+            // a pinch starts, or its fingers changed: start over from here
+            this.offset   = null
+            this.dragItem = null
+            this.pinch    = {
+                distance : Math.max(Math.hypot(b[0] - a[0], b[1] - a[1]), 1),
+                scale    : this.scale,
+                point    : this.Surface(middle()),
+                }
+        }
+        else if (event.type === 'pointermove' && this.pinch && this.touches.size >= 2) {
+            let distance = Math.hypot(b[0] - a[0], b[1] - a[1])
+            this.ZoomTo(this.pinch.scale * distance / this.pinch.distance)
+            this.PanTo(this.pinch.point, middle())
+        }
+
+        if (this.pinch) {
+            if (this.touches.size === 0) {
+                this.pinch = null
+            }
+            event.preventDefault()
+            event.stopImmediatePropagation()
+        }
+    }
+
     OnMouseWheel(event) {
-        this.Zoom(normalizeWheel(event))
+        // a zero delta (a horizontal-only scroll) would reset the zoom to 1.0
+        let delta = normalizeWheel(event)
+        if (delta) {
+            this.Zoom(delta, this.Local(event.clientX, event.clientY))
+        }
         //this.$('#zoomslider').slider('option', 'value', this.scale)
         return cancelEvent(event)
     }
@@ -219,6 +349,7 @@ class Avispa extends Backbone.View {
     MiddleClick(event) {}
     RightClick(event) {}
     OnContextMenu(event) {}
+    OnMessage(msg) {}
 }
 
 exports.Avispa      = Avispa
@@ -226,5 +357,6 @@ exports.Position    = Position
 exports.Group       = Group
 exports.Node        = Node
 exports.Link        = Link
+exports.Socket      = Socket
 exports.$SVG        = $SVG
 exports.cancelEvent = cancelEvent

package/js/BaseObject.js

@@ -8,13 +8,20 @@ const context         = require('./Context.js')
 
 
 class BaseObject extends Backbone.View {
+    // render once the whole initialize chain has run, so a subclass's own
+    // elements exist before its render does
+    constructor(options) {
+        super(options)
+        this.render()
+    }
+
     events() {
         return {
-            'mousedown'   : 'OnMouseDown',
-            'mouseenter'  : 'OnMouseEnter',
-            'mouseleave'  : 'OnMouseLeave',
-            'mouseup'     : 'OnMouseUp',
-            'contextmenu' : 'OnContextMenu',
+            'pointerdown'  : 'OnMouseDown',
+            'pointerenter' : 'OnMouseEnter',
+            'pointerleave' : 'OnMouseLeave',
+            'pointerup'    : 'OnMouseUp',
+            'contextmenu'  : 'OnContextMenu',
             }
     }
 
@@ -26,22 +33,61 @@ class BaseObject extends Backbone.View {
         _.bindAll(this, 'OnMouseDown', 'OnMouseUp', 'OnContextMenu', 'render')
 
         this.parent   = options.parent
+        this.children = []
         this.position = options.position
-        if (this.position) {
-            this.position.bind('change', this.render, this)
-        }
 
         if (this.parent) {
+            this.parent.children.push(this)
             this.offset = {
                 x: this.position.get('x'),
                 y: this.position.get('y'),
                 }
             this.ParentDrag(this.parent.position)
-            this.parent.position.bind('change', this.ParentDrag, this)
+            this.listenTo(this.parent.position, 'change', this.ParentDrag)
+            this.$el.css('display', this.CollapsedAncestor() ? 'none' : '')
+        }
+
+        // bound after the initial ParentDrag: a subclass is still building its
+        // elements here, and the constructor renders once initialize is done
+        if (this.position) {
+            this.listenTo(this.position, 'change', this.render)
+        }
+    }
+
+    // stopListening (in Backbone's remove) drops the model listeners; leaving
+    // the parent's children keeps a removed item out of its sizing and collapse
+    remove() {
+        if (this.parent) {
+            this.parent.children = _.without(this.parent.children, this)
+        }
+        return super.remove()
+    }
+
+    // the outermost collapsed group containing this item, or null if it is on screen
+    CollapsedAncestor() {
+        let collapsed = null
+        for (let p = this.parent; p; p = p.parent) {
+            if (p.position.get('collapsed')) {
+                collapsed = p
+            }
+        }
+        return collapsed
+    }
+
+    // how far this item reaches into its parent group, from the parent's top-left
+    Extent() {
+        return [this.offset.x, this.offset.y]
+    }
+
+    // hide everything inside a collapsed group, and show it again on expand
+    UpdateVisibility() {
+        for (const child of this.children) {
+            child.$el.css('display', child.CollapsedAncestor() ? 'none' : '')
+            child.UpdateVisibility()
         }
     }
 
-    size(w,h) {
+    Size(w,h) {
         this.position.set({w:w,h:h})
         return this
     }

package/js/Group.js

@@ -9,10 +9,24 @@ const BaseObject            = require('./BaseObject.js')
 
 
 class Group extends BaseObject {
+    // a collapsed group shrinks to its title bar: the 30px a child group keeps
+    // clear at the top in Drag
+    static COLLAPSED_HEIGHT = 30
+
+    // the resize handle in the bottom-right corner, and the smallest a group gets
+    static HANDLE   = 10
+    static MIN_SIZE = 40
+
     el() {
         return $SVG('g').attr('class', 'group')
     }
 
+    events() {
+        return Object.assign(super.events(), {
+            'pointerdown rect.handle' : 'OnHandleDown',
+            })
+    }
+
     initialize(options) {
         this.$rect = $SVG('rect')
             .attr('width',  options.position.get('w'))
@@ -20,18 +34,113 @@ class Group extends BaseObject {
             .css('fill', options.position.get('fill'))
             .appendTo(this.$el)
 
+        this.$handle = $SVG('rect')
+            .attr('class',  'handle')
+            .attr('width',  Group.HANDLE)
+            .attr('height', Group.HANDLE)
+            .appendTo(this.$el)
+
         super.initialize(options)
+
+        this.listenTo(this.position, 'change:collapsed', this.UpdateVisibility)
     }
 
     render() {
+        let x = this.position.get('x')
+        let y = this.position.get('y')
+        let w = this.position.get('w')
+        let h = this.Height()
+
         this.$rect
-            .attr('width',  this.position.get('w'))
-            .attr('height', this.position.get('h'))
-            .attr('x',      this.position.get('x'))
-            .attr('y',      this.position.get('y'))
+            .attr('width',  w)
+            .attr('height', h)
+            .attr('x',      x)
+            .attr('y',      y)
+
+        // no resizing while collapsed
+        this.$handle
+            .attr('x', x + w - Group.HANDLE)
+            .attr('y', y + h - Group.HANDLE)
+            .css('display', this.position.get('collapsed') ? 'none' : '')
+
         return this
     }
 
+    // drawn height; `h` keeps the expanded height while collapsed
+    Height() {
+        return this.position.get('collapsed') ? Group.COLLAPSED_HEIGHT : this.position.get('h')
+    }
+
+    Collapse() {
+        this.position.set({collapsed: true})
+        return this
+    }
+
+    Expand() {
+        this.position.set({collapsed: false})
+        return this
+    }
+
+    ToggleCollapse() {
+        this.position.set({collapsed: !this.position.get('collapsed')})
+        return this
+    }
+
+    // set the size, but no smaller than the group's contents, and grow the
+    // parent group if this one no longer fits inside it
+    Resize(w, h) {
+        let [minw, minh] = this.MinSize()
+        this.Size(Math.max(w, minw), Math.max(h, minh))
+
+        if (this.parent) {
+            let [pw, ph] = this.Extent()
+            this.parent.Resize(
+                Math.max(this.parent.position.get('w'), pw),
+                Math.max(this.parent.position.get('h'), ph))
+        }
+        return this
+    }
+
+    // the smallest size that still holds every child
+    MinSize() {
+        let w = Group.MIN_SIZE
+        let h = Group.MIN_SIZE
+        for (const child of this.children) {
+            let [cw, ch] = child.Extent()
+            w = Math.max(w, cw)
+            h = Math.max(h, ch)
+        }
+        return [w, h]
+    }
+
+    // the room this group needs inside its parent, keeping the 10px margin of Drag
+    Extent() {
+        return [
+            this.offset.x + this.position.get('w') + 10,
+            this.offset.y + this.Height() + 10,
+            ]
+    }
+
+    // dragging the handle resizes the group, through a drag item of its own so
+    // the group's click hooks don't fire for it
+    OnHandleDown(event) {
+        let start = {
+            x: event.clientX,
+            y: event.clientY,
+            w: this.position.get('w'),
+            h: this.position.get('h'),
+            }
+
+        context.a.dragItem = {
+            jitter: 0,
+            Drag: (event) => this.Resize(
+                start.w + (event.clientX - start.x) / context.a.scale,
+                start.h + (event.clientY - start.y) / context.a.scale),
+            }
+
+        return cancelEvent(event)
+    }
+
     OnMouseEnter(event) {
         if (!context.a.dragItem) {
             this.$rect.attr('class', 'hover')
@@ -58,7 +167,7 @@ class Group extends BaseObject {
             this.offset.y = this.oy1 + y
 
             let boundsx = this.parent.position.get('w') - this.position.get('w') - 10
-            let boundsy = this.parent.position.get('h') - this.position.get('h') - 10
+            let boundsy = this.parent.position.get('h') - this.Height() - 10
 
             if (this.offset.x < 10) {
                 this.offset.x = 10

package/js/Link.js

@@ -10,16 +10,22 @@ const context               = require('./Context.js')
 class Link extends Backbone.View {
     static RAD = 180.0 / Math.PI
 
+    // render once the whole initialize chain has run, as BaseObject does
+    constructor(options) {
+        super(options)
+        this.render()
+    }
+
     el() {
         return $SVG('g').attr('class', 'link')
     }
 
     events() {
         return {
-            'mousedown'   : 'OnMouseDown',
-            'mouseenter'  : 'OnMouseEnter',
-            'mouseleave'  : 'OnMouseLeave',
-            'contextmenu' : 'OnContextMenu',
+            'pointerdown'  : 'OnMouseDown',
+            'pointerenter' : 'OnMouseEnter',
+            'pointerleave' : 'OnMouseLeave',
+            'contextmenu'  : 'OnContextMenu',
             }
     }
 
@@ -32,14 +38,19 @@ class Link extends Backbone.View {
         _.bindAll(this, 'render', 'OnMouseDown', 'OnMouseEnter', 'OnMouseLeave', 'OnContextMenu')
 
         this.arc = new Backbone.Model({arc:10})
-        this.arc.bind('change', this.render, this)
+        this.listenTo(this.arc, 'change', this.render)
 
         this.left  = options.left
         this.right = options.right
-        this.left.position.bind('change', this.render, this)
-        this.right.position.bind('change', this.render, this)
+        this.listenTo(this.left.position,  'change', this.render)
+        this.listenTo(this.right.position, 'change', this.render)
 
-        this.render()
+        // re-render when a group around either end collapses or expands
+        for (const end of [this.left, this.right]) {
+            for (let p = end.parent; p; p = p.parent) {
+                this.listenTo(p.position, 'change:collapsed', this.render)
+            }
+        }
 
         if (options.parent) {
             options.parent.$links.append(this.$el)
@@ -51,14 +62,49 @@ class Link extends Backbone.View {
         return
     }
 
+    // the items the ends attach to: an end hidden inside a collapsed group
+    // attaches to that group instead
+    Ends() {
+        return [
+            this.left.CollapsedAncestor()  || this.left,
+            this.right.CollapsedAncestor() || this.right,
+            ]
+    }
+
+    // the point a link aims at: a node's center, or the middle of a collapsed group
+    static Center(item) {
+        let p = item.position
+        if (p.get('collapsed')) {
+            return [p.get('x') + p.get('w') / 2, p.get('y') + item.Height() / 2]
+        }
+        return [p.get('x'), p.get('y')]
+    }
+
+    // distance from Center(item) to the item's edge along the unit vector (ux, uy)
+    static Edge(item, ux, uy) {
+        if (!item.position.get('collapsed')) {
+            return 30
+        }
+        return Math.min(
+            item.position.get('w') / 2 / Math.abs(ux),
+            item.Height()          / 2 / Math.abs(uy))
+    }
+
     render() {
         if (!this.arc) { return this }
 
+        let [left, right] = this.Ends()
+
+        // both ends are hidden inside the same collapsed group
+        if (left === right) {
+            this.$el.css('display', 'none')
+            return this
+        }
+        this.$el.css('display', '')
+
         let arc = this.arc.get('arc')
-        let lx = this.left.position.get('x')
-        let ly = this.left.position.get('y')
-        let rx = this.right.position.get('x')
-        let ry = this.right.position.get('y')
+        let [lx, ly] = Link.Center(left)
+        let [rx, ry] = Link.Center(right)
 
         // calculate the angle between 2 nodes
         let ang = Math.atan2(rx - lx, ry - ly)
@@ -66,11 +112,15 @@ class Link extends Backbone.View {
         // bound the offset to about half the circle
         let offset = Math.max(-1.5, Math.min(1.5, arc / 100))
 
-        // draw to the edge of the node
-        lx +=  30 * Math.sin(ang + offset)
-        ly +=  30 * Math.cos(ang + offset)
-        rx += -33 * Math.sin(ang - offset)
-        ry += -33 * Math.cos(ang - offset)
+        // draw to the edge of each end, leaving room for the arrowhead
+        let la = ang + offset
+        let ra = ang - offset
+        let ld = Link.Edge(left,  Math.sin(la), Math.cos(la))
+        let rd = Link.Edge(right, Math.sin(ra), Math.cos(ra)) + 3
+        lx += ld * Math.sin(la)
+        ly += ld * Math.cos(la)
+        rx -= rd * Math.sin(ra)
+        ry -= rd * Math.cos(ra)
 
         // calculate the the position for the quadratic bezier curve
         let xc = ((lx + rx) >> 1) + arc * Math.cos(ang)
@@ -79,11 +129,11 @@ class Link extends Backbone.View {
         let mx = xc - (arc>>1) * Math.cos(ang)
         let my = yc + (arc>>1) * Math.sin(ang)
 
-        let rot = -(this.RAD * ang)
+        let rot = -(Link.RAD * ang)
         rot += (rot > 0 && rot < 180) ? -90 : 90
 
-        this.path.attr('d', "M #{lx} #{ly} Q #{xc} #{yc} #{rx} #{ry}")
-        //this.label.attr('x', mx).attr('y', my).attr('transform', "rotate(#{rot}, #{mx} #{my})")
+        this.path.attr('d', `M ${lx} ${ly} Q ${xc} ${yc} ${rx} ${ry}`)
+        //this.label.attr('x', mx).attr('y', my).attr('transform', `rotate(${rot}, ${mx} ${my})`)
 
         return this
     }
@@ -93,15 +143,14 @@ class Link extends Backbone.View {
     Drag(event) {
         let [x,y] = context.a.Point(event)
 
-        let from_x = this.left.position.get('x')
-        let from_y = this.left.position.get('y')
-        let to_x   = this.right.position.get('x')
-        let to_y   = this.right.position.get('y')
+        let [left, right]    = this.Ends()
+        let [from_x, from_y] = Link.Center(left)
+        let [to_x, to_y]     = Link.Center(right)
 
         let d = (to_x - from_x) * (y - from_y) - (to_y - from_y) * (x - from_x)
 
         if (d) {
-            d = Math.pow(Math.abs(d), 0.5) * (d > 0) ? -1 : 1
+            d = Math.pow(Math.abs(d), 0.5) * ((d > 0) ? -1 : 1)
         }
 
         if (!this.od && this.od != 0) {
@@ -123,7 +172,7 @@ class Link extends Backbone.View {
     }
 
     MouseUp(event) {
-        if (this.jitter > 3) {
+        if (this.jitter >= 3) {
             this.path.css('stroke-width', '3px')
         }
     }

package/js/Node.js

@@ -27,8 +27,6 @@ class Node extends BaseObject {
             .appendTo(this.$el)
 
         super.initialize(options)
-
-        this.render()
     }
 
     render() {
@@ -41,6 +39,12 @@ class Node extends BaseObject {
         return this
     }
 
+    // the whole circle, not just its center, belongs inside the parent group
+    Extent() {
+        let r = this.position.get('radius') || 0
+        return [this.offset.x + r, this.offset.y + r]
+    }
+
     OnMouseEnter(event) {
         if (!context.a.dragItem) {
             this.$circle.attr('class', 'hover')

package/js/Socket.js

@@ -0,0 +1,134 @@
+'use strict'
+
+
+const DEFAULTS = {
+    url       : null,   // full ws(s):// URL; overrides `path` when set
+    path      : 'ws',   // path appended to the current host
+    timeout   : 0.9375, // seconds before the first reconnect attempt
+    maxtime   : 60,     // reconnect backoff is capped at this many seconds
+    ping      : 300,    // seconds between keepalive pings (0 disables)
+    onopen    : function(event) {},
+    onclose   : function(event) {},
+    onerror   : function(error) {},
+    onmessage : function(msg) {},
+}
+
+
+class Socket {
+    constructor(options) {
+        this.options = Object.assign({}, DEFAULTS, options)
+
+        if (this.options.url) {
+            this.wsurl = this.options.url
+        }
+        else {
+            let protocol = location.protocol.replace('http', 'ws')
+            this.wsurl = `${protocol}//${location.host}/${this.options.path}`
+        }
+
+        this.timeout  = this.options.timeout
+        this.interval = null
+        this.retry    = null
+        this.queue    = []
+        this.closed   = false
+
+        this.connect()
+    }
+
+    connect() {
+        this.ws = new WebSocket(this.wsurl)
+
+        this.ws.onopen = (event) => {
+            // successful connection: reset the backoff and flush queued sends
+            this.timeout = this.options.timeout
+
+            for (const message of this.queue.splice(0)) {
+                this.ws.send(message)
+            }
+
+            if (this.options.ping) {
+                this.interval = setInterval(() => {
+                    if (this.ws.readyState === WebSocket.OPEN) {
+                        this.ws.send('ping')
+                    }
+                }, 1000 * this.options.ping)
+            }
+
+            this.options.onopen(event)
+        }
+
+        this.ws.onmessage = (event) => {
+            if (event.data === 'pong') {
+                return
+            }
+
+            let msg
+            try {
+                msg = JSON.parse(event.data)
+            }
+            catch (error) {
+                this.options.onerror(error)
+                return
+            }
+
+            this.options.onmessage(msg)
+        }
+
+        this.ws.onerror = (event) => {
+            this.options.onerror(event)
+        }
+
+        this.ws.onclose = (event) => {
+            clearInterval(this.interval)
+            this.interval = null
+
+            this.options.onclose(event)
+
+            // application-level signal to force a full page reload
+            if (event.code === 4004) {
+                window.location.reload()
+                return
+            }
+
+            // deliberate close() — do not reconnect
+            if (this.closed) {
+                return
+            }
+
+            this.retry = setTimeout(() => {
+                this.retry = null
+                this.connect()
+            }, 1000 * this.timeout)
+
+            // exponential backoff on every attempt, capped at maxtime
+            this.timeout = Math.min(this.timeout * 2, this.options.maxtime)
+        }
+    }
+
+    send(message) {
+        this.sendraw(JSON.stringify(message))
+    }
+
+    sendraw(message) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(message)
+        }
+        else {
+            // queued until the (re)connection opens
+            this.queue.push(message)
+        }
+    }
+
+    close() {
+        this.closed = true
+        clearInterval(this.interval)
+        clearTimeout(this.retry)
+        this.interval = null
+        this.retry    = null
+        if (this.ws) {
+            this.ws.close()
+        }
+    }
+}
+
+module.exports = Socket

package/js/Types.js

@@ -3,7 +3,7 @@
 const Backbone = require('backbone')
 
 class Position extends Backbone.Model {}
-class Arc extends Backbone.Model {}
+class Arc      extends Backbone.Model {}
 
 exports.Position = Position
 exports.Arc      = Arc

package/js/Utils.js

@@ -2,15 +2,23 @@
 
 const $ = require('jquery')
 
-
 exports.cancelEvent = function(event) {
     event.preventDefault()
     event.stopPropagation()
     return false
 }
 
+exports.$SVG = function(name) {
+    return $(document.createElementNS('http://www.w3.org/2000/svg', name))
+}
+
+// zoom steps for a `wheel` event: about 1 per mouse-wheel notch, positive when
+// scrolling up. jQuery doesn't copy the deltas, so read the native event.
 exports.normalizeWheel = function(event) {
-    if (event.wheelDelta) return event.wheelDelta / 120
-    if (event.detail)     return event.detail     /  -3
-    return 0
+    event = event.originalEvent || event
+    switch (event.deltaMode) {
+        case 0:  return -event.deltaY / 100        // pixels: ~100 per notch
+        case 1:  return -event.deltaY / 3          // lines: 3 per notch
+        default: return -Math.sign(event.deltaY)   // pages
+    }
 }

package/package.json

@@ -1,12 +1,28 @@
 {
   "name": "@shawcx/avispa",
-  "version": "1.0.0",
-  "description": "SVG + Websockets",
+  "version": "2.1.0",
+  "description": "Draw node/link graphs in SVG and drag, pan, zoom, and collapse them; Backbone views with an optional WebSocket feed",
+  "keywords": [
+    "svg",
+    "graph",
+    "network",
+    "diagram",
+    "backbone",
+    "websocket"
+  ],
   "main": "js/Avispa.js",
   "sass": "scss/Avispa.scss",
   "style": "css/Avispa.css",
+  "files": [
+    "js",
+    "css",
+    "scss"
+  ],
   "scripts": {
-    "build": "npx sass scss/Avispa.scss css/Avispa.css"
+    "build": "npx sass scss/Avispa.scss css/Avispa.css",
+    "example": "npm --prefix example install && npm --prefix example start",
+    "test": "playwright test",
+    "pretest": "npm --prefix example install --no-audit --no-fund && npm --prefix example run build"
   },
   "repository": {
     "type": "git",
@@ -18,12 +34,16 @@
     "url": "https://github.com/shawcx/avispa/issues"
   },
   "homepage": "https://github.com/shawcx/avispa#readme",
-  "dependencies": {
+  "peerDependencies": {
     "backbone": "^1.4.1",
-    "jquery": "^3.6.3",
+    "jquery": "^3.6.3 || ^4.0.0",
     "underscore": "^1.13.6"
   },
   "devDependencies": {
-    "sass": "^1.58.2"
+    "@playwright/test": "^1.64.1",
+    "backbone": "^1.4.1",
+    "jquery": "^3.6.3 || ^4.0.0",
+    "sass": "^1.106.1",
+    "underscore": "^1.13.6"
   }
 }

package/scss/Avispa.scss

@@ -17,9 +17,15 @@ g.group {
         stroke-width: 2px;
     }
 
+    rect.handle {
+        cursor: nwse-resize;
+        fill: #999;
+        stroke: none;
+    }
+
     text {
         cursor: pointer;
-        font: bold 8pt $mono;
+        font: bold 10pt $mono;
         fill: #000;
         text-anchor: left;
     }