fix(joint-core): keep blank pointerdown compatible, add paper eventSurface

The previous commit made `pointerdown` run the full `guard()` even when the
press hit no cell view. That is a breaking change: `guard()` rejects any target
that is not on the paper's event surface, so HTML rendered into `paper.el` -
a ruler, a gutter, a toolbar - stopped opening a blank interaction. The whole
gesture went with it, because the document-level drag listeners are delegated
from `pointerdown`.

Restore the old answer while keeping a way to opt out. `guard()` is split in two:

- `guardExplicit()` - decisions made about this very event: the right mouse
  button, the `guard` option, an `evt.data.guarded` flag.
- `guard()` - unchanged: `guardExplicit()`, then judge the target itself (its
  tag name, its view, the event surface).

A press that hit no cell view now consults only `guardExplicit()`. So the press
opens a blank interaction as it always has, and `options.guard` can veto it -
which was impossible before, since `guard()` was not consulted on that path at
all. Behaviour is otherwise bit-exact: `GUARDED_TAG_NAMES` still judges the
target, so a `<select>` in an overlay is not treated differently.

The remaining asymmetry - such content gets `blank:pointerdown` but no
`blank:pointerclick` and no hover - is now addressable rather than baked in. The
new `eventSurface` paper option declares a DOM subtree part of the interaction
surface, and every handler then treats it as a blank area:

    new dia.Paper({ eventSurface: '.ruler' })

It takes a CSS selector (matched with `closest`, so it covers any number of
subtrees), an element, an array of elements, or a predicate. `guard` is
consulted first, so single events can still be vetoed within a surface.

Also types `guard`'s `view` parameter as optional - it has always been called
without a view from `pointerclick`, `mouseover` and the other handlers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: kumilingus

packages/joint-core/src/dia/Paper.mjs

@@ -342,6 +342,16 @@ export const Paper = View.extend({
             return false;
         },
 
+        // Extra DOM content inside `el` that counts as part of the paper's interaction
+        // surface. By default only the paper element itself and the SVG document do, so a
+        // press on HTML rendered into `el` (an overlay, a popup, a toolbar) is guarded.
+        // Opting a subtree back in makes the paper treat it as it treats a blank area
+        // (`blank:pointerdown`, `blank:pointerclick`, `blank:mouseover`, ...).
+        // A CSS selector (matched with `closest`, so it may cover any number of subtrees),
+        // an element, an array of elements, or a `function(target) { return boolean; }`.
+        // `guard` is consulted first, so single events can still be vetoed within a surface.
+        eventSurface: null,
+
         highlighting: defaultHighlighting,
 
         // Prevent the default context menu from being displayed.
@@ -3476,14 +3486,16 @@ export const Paper = View.extend({
         const view = this.findView(target);
         const isContextMenu = (button === 2);
 
-        // Guard before any interaction starts, on blank areas too. Every other pointer
-        // handler (`pointerclick`, `pointerdblclick`, `contextMenuTrigger`, `mouseover`, …)
-        // guards unconditionally; guarding only the `view` branch let a press on non-SVG
-        // content inside `el` (an HTML overlay, a popup, a toolbar) start a blank
-        // interaction even though `guard()` rejects that target — and the matching
-        // `blank:pointerclick` was then guarded, so the events came out asymmetric.
-        // `contextmenu` stays exempt: `contextMenuTrigger()` runs its own guard.
-        if (!isContextMenu && this.guard(evt, view)) return;
+        if (!isContextMenu) {
+            // A press that did not hit a cell view is guarded too, so that DOM content
+            // inside `el` (an overlay, a popup, a toolbar) can opt out of opening a blank
+            // interaction. Only an explicit veto counts there: the full `guard()` also
+            // rejects anything outside the event surface, and such a press has always
+            // opened a blank interaction. Opt the content into `eventSurface` to have
+            // every other paper event treat it the same way.
+            // `contextmenu` is exempt: `contextMenuTrigger()` runs its own guard.
+            if (view ? this.guard(evt, view) : this.guardExplicit(evt, view)) return;
+        }
 
         if (view) {
 
@@ -3896,6 +3908,34 @@ export const Paper = View.extend({
     // Otherwise, it returns `false`.
     guard: function(evt, view) {
 
+        const guarded = this.guardExplicit(evt, view);
+        if (guarded !== undefined) {
+            return guarded;
+        }
+
+        const { target } = evt;
+
+        if (this.GUARDED_TAG_NAMES.includes(target.tagName)) {
+            return true;
+        }
+
+        if (view && view.model && (view.model[CELL_MARKER])) {
+            return false;
+        }
+
+        if (this.el === target || this.svg.contains(target) || this.isEventSurface(target)) {
+            return false;
+        }
+
+        return true;    // Event guarded. Paper should not react on it in any way.
+    },
+
+    // The part of `guard()` that reflects a decision made about this very event: the right
+    // mouse button, the `guard` option, an `evt.data.guarded` flag. Returns `undefined`
+    // when none of them has an opinion, leaving the answer to the caller - `guard()` then
+    // goes on to judge the target itself (its tag name, its view, the event surface).
+    guardExplicit: function(evt, view) {
+
         if (evt.type === 'mousedown' && evt.button === 2) {
             // handled as `contextmenu` type
             return true;
@@ -3909,21 +3949,28 @@ export const Paper = View.extend({
             return evt.data.guarded;
         }
 
-        const { target } = evt;
+        return undefined;
+    },
 
-        if (this.GUARDED_TAG_NAMES.includes(target.tagName)) {
-            return true;
-        }
+    // Is `target` part of the paper's interaction surface? The SVG document always is;
+    // other DOM content inside `el` is only when the `eventSurface` option says so.
+    isEventSurface: function(target) {
 
-        if (view && view.model && (view.model[CELL_MARKER])) {
-            return false;
+        const { eventSurface } = this.options;
+        if (!eventSurface) return false;
+        // `target` is not guaranteed to be an element (e.g. the document).
+        if (!(target instanceof Element)) return false;
+
+        if (isFunction(eventSurface)) {
+            return !!eventSurface.call(this, target);
         }
 
-        if (this.el === target || this.svg.contains(target)) {
-            return false;
+        if (isString(eventSurface)) {
+            return !!target.closest(eventSurface);
         }
 
-        return true;    // Event guarded. Paper should not react on it in any way.
+        const surfaces = Array.isArray(eventSurface) ? eventSurface : [eventSurface];
+        return surfaces.some((el) => el instanceof Element && el.contains(target));
     },
 
     setGridSize: function(gridSize) {

packages/joint-core/test/jointjs/paper.js

@@ -1240,13 +1240,13 @@ QUnit.module('paper', function(hooks) {
         assert.ok(diffX < 5 && diffY < 5, 'element should not have been moved');
     });
 
-    QUnit.test('pointerdown is guarded on blank areas too', function(assert) {
+    QUnit.test('a press on DOM content inside the paper can be guarded', function(assert) {
 
-        // A press on non-SVG content inside `paper.el` (an HTML overlay, popup or
-        // toolbar) must not start a blank interaction: `guard()` rejects such a target,
-        // and every other pointer handler honours that. `pointerdown` used to consult
-        // `guard()` only when a cell view was found, so `blank:pointerdown` fired for
-        // overlay content while the matching `blank:pointerclick` stayed guarded.
+        // `guard()` rejects a target that is not on the event surface, so an HTML overlay,
+        // popup or toolbar inside `paper.el` gets no `blank:pointerclick` and no hover
+        // events. A press on one has always opened a blank interaction regardless, and
+        // still does - but `pointerdown` now consults the `guard` option there too, so an
+        // overlay can opt out of it.
         const overlayEl = document.createElement('div');
         this.paper.el.appendChild(overlayEl);
 
@@ -1261,18 +1261,156 @@ QUnit.module('paper', function(hooks) {
         simulate.mousedown({ el: overlayEl, clientX: 10, clientY: 10 });
         simulate.mouseup({ el: overlayEl, clientX: 10, clientY: 10 });
 
-        assert.equal(blankPointerdownCount, 0,
-            'no blank:pointerdown for a press on HTML content inside the paper');
+        assert.equal(blankPointerdownCount, 1,
+            'a press on HTML content inside the paper opens a blank interaction');
 
-        // A genuine blank press (on the SVG) must still work.
+        // The `guard` option vetoes it.
+        this.paper.options.guard = function(evt) {
+            return overlayEl.contains(evt.target);
+        };
+
+        simulate.mousedown({ el: overlayEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: overlayEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 1, 'the guard option prevents it');
+
+        // A genuine blank press (on the SVG) is unaffected by that guard.
         simulate.mousedown({ el: this.paper.svg, clientX: 10, clientY: 10 });
         simulate.mouseup({ el: this.paper.svg, clientX: 10, clientY: 10 });
 
-        assert.equal(blankPointerdownCount, 1, 'blank:pointerdown still fires on the SVG');
+        assert.equal(blankPointerdownCount, 2, 'blank:pointerdown still fires on the SVG');
+
+        // Only the `guard` option, `evt.data.guarded` and the right button speak for a
+        // press that hit no cell view. `GUARDED_TAG_NAMES` judges the target instead, and
+        // stays out of it: a <select> in an overlay opens a blank interaction like any
+        // other DOM content there, exactly as it always has.
+        this.paper.options.guard = null;
+        const selectEl = document.createElement('select');
+        overlayEl.appendChild(selectEl);
+
+        assert.equal(this.paper.guard({ type: 'mousedown', button: 0, target: selectEl }), true,
+            'guard() still rejects a <select>');
+
+        simulate.mousedown({ el: selectEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: selectEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 3, 'a <select> in an overlay is not treated differently');
 
         overlayEl.remove();
     });
 
+    QUnit.test('eventSurface opts DOM content inside the paper back in', function(assert) {
+
+        // HTML rendered into `paper.el` - a ruler, a gutter, a toolbar - is only half
+        // interactive: a press opens a blank interaction, but every other handler runs the
+        // full `guard()`, which rejects a target that is not on the event surface. So the
+        // gesture comes out asymmetric: `blank:pointerdown` and the drag that follows it,
+        // but no `blank:pointerclick` and no hover. `eventSurface` declares the subtree
+        // part of the surface and the paper then treats all of it as a blank area.
+        const rulerEl = document.createElement('div');
+        rulerEl.className = 'ruler';
+        const tickEl = document.createElement('span');
+        rulerEl.appendChild(tickEl);
+        this.paper.el.appendChild(rulerEl);
+
+        const events = [];
+        this.paper.on('blank:pointerdown', () => events.push('pointerdown'));
+        this.paper.on('blank:pointermove', () => events.push('pointermove'));
+        this.paper.on('blank:pointerup', () => events.push('pointerup'));
+        this.paper.on('blank:pointerclick', () => events.push('pointerclick'));
+        this.paper.on('blank:mouseover', () => events.push('mouseover'));
+
+        simulate.mouseover({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mousedown({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: tickEl, clientX: 10, clientY: 10 });
+
+        assert.deepEqual(events, ['pointerdown', 'pointerup'],
+            'without eventSurface the gesture is missing its click and hover');
+
+        // Pressing a descendant works: the selector is matched with `closest()`.
+        events.length = 0;
+        this.paper.options.eventSurface = '.ruler';
+
+        simulate.mouseover({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mousedown({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: tickEl, clientX: 10, clientY: 10 });
+
+        assert.deepEqual(events, ['mouseover', 'pointerdown', 'pointerup', 'pointerclick'],
+            'the surfaced content produces the complete blank gesture');
+
+        // A drag started on the ruler is tracked to completion.
+        events.length = 0;
+        simulate.mousedown({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mousemove({ el: tickEl, clientX: 100, clientY: 100 });
+        simulate.mouseup({ el: tickEl, clientX: 100, clientY: 100 });
+
+        assert.deepEqual(events, ['pointerdown', 'pointermove', 'pointerup'],
+            'a drag from the surfaced content is tracked (and is not a click)');
+
+        rulerEl.remove();
+    });
+
+    QUnit.test('eventSurface forms, and guard still wins', function(assert) {
+
+        const rulerEl = document.createElement('div');
+        rulerEl.className = 'ruler';
+        const tickEl = document.createElement('span');
+        rulerEl.appendChild(tickEl);
+        this.paper.el.appendChild(rulerEl);
+
+        const otherEl = document.createElement('div');
+        this.paper.el.appendChild(otherEl);
+
+        const { paper } = this;
+        const isSurface = (el) => paper.isEventSurface(el);
+
+        paper.options.eventSurface = null;
+        assert.notOk(isSurface(tickEl), 'nothing is surfaced by default');
+
+        paper.options.eventSurface = '.ruler';
+        assert.ok(isSurface(tickEl), 'selector: matches a descendant');
+        assert.notOk(isSurface(otherEl), 'selector: does not match outside the subtree');
+
+        paper.options.eventSurface = rulerEl;
+        assert.ok(isSurface(tickEl), 'element: matches a descendant');
+        assert.notOk(isSurface(otherEl), 'element: does not match outside the subtree');
+
+        paper.options.eventSurface = [rulerEl, otherEl];
+        assert.ok(isSurface(tickEl) && isSurface(otherEl), 'array: matches either subtree');
+
+        paper.options.eventSurface = (target) => target === otherEl;
+        assert.ok(isSurface(otherEl), 'function: matches what it accepts');
+        assert.notOk(isSurface(tickEl), 'function: rejects the rest');
+
+        // `target` is not always an element - `document` must not throw.
+        paper.options.eventSurface = '.ruler';
+        assert.notOk(isSurface(document), 'a non-element target is never a surface');
+
+        // `guard` is consulted before the surface test, so it can still veto single
+        // events within a surface - here the ruler stays hoverable but not pressable.
+        let blankPointerdownCount = 0;
+        let blankMouseoverCount = 0;
+        paper.on('blank:pointerdown', function() {
+            blankPointerdownCount += 1;
+        });
+        paper.on('blank:mouseover', function() {
+            blankMouseoverCount += 1;
+        });
+        paper.options.guard = function(evt) {
+            return evt.type === 'mousedown' && rulerEl.contains(evt.target);
+        };
+
+        simulate.mouseover({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mousedown({ el: tickEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: tickEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 0, 'guard vetoes the press inside the surface');
+        assert.equal(blankMouseoverCount, 1, 'the surface is still hoverable');
+
+        rulerEl.remove();
+        otherEl.remove();
+    });
+
     QUnit.test('a press on a form control does not drag the element', function(assert) {
 
         // FORM_CONTROL_TAG_NAMES marks a press on a <button>/<input>/<select>/<textarea>/

packages/joint-core/test/ts/index.test.ts

@@ -160,6 +160,16 @@ const paper = new joint.dia.Paper({
 
 paper.fitToContent({ padding: { top: 10  }, allowNewOrigin: false });
 
+// `eventSurface` accepts a selector, an element, an array of elements or a predicate.
+const rulerEl = document.createElement('div');
+new joint.dia.Paper({ model: graph, eventSurface: '.ruler' });
+new joint.dia.Paper({ model: graph, eventSurface: rulerEl });
+new joint.dia.Paper({ model: graph, eventSurface: [rulerEl] });
+new joint.dia.Paper({ model: graph, eventSurface: (target) => target.classList.contains('ruler') });
+new joint.dia.Paper({ model: graph, eventSurface: null });
+// `guard` is called without a view when the event did not hit a cell view.
+new joint.dia.Paper({ model: graph, guard: (_evt, view) => view?.model.isElement() ?? false });
+
 const cellView = graph.getCells()[0].findView(paper);
 cellView.vel.addClass('test-class');
 

packages/joint-core/types/dia.d.ts

@@ -1760,7 +1760,10 @@ export namespace Paper {
         linkPinning?: boolean;
         allowLink?: ((linkView: LinkView, paper: Paper) => boolean) | null;
         // events
-        guard?: (evt: Event, view: CellView) => boolean;
+        // `view` is undefined when the event did not hit a cell view (a blank area,
+        // or DOM content inside the paper element).
+        guard?: (evt: Event, view?: CellView) => boolean;
+        eventSurface?: string | DOMElement | DOMElement[] | ((target: DOMElement) => boolean) | null;
         preventContextMenu?: boolean;
         preventDefaultViewAction?: boolean;
         preventDefaultBlankAction?: boolean;
@@ -2333,7 +2336,11 @@ export class Paper extends mvc.View<Graph> {
 
     protected onlabel(evt: Event): void;
 
-    protected guard(evt: Event, view: CellView): boolean;
+    protected guard(evt: Event, view?: CellView): boolean;
+
+    protected guardExplicit(evt: Event, view?: CellView): boolean | undefined;
+
+    protected isEventSurface(target: EventTarget | null): boolean;
 
     protected drawBackgroundImage(img: HTMLImageElement | null, opt?: { [key: string]: any }): void;