fix: let the guard option veto a blank pointerdown; buttons that click and drag

[kumilingus]

Supersedes #3437 — carries its commit unchanged (credit to @samuelgja) and builds on it.

1. fix(joint-core): options.guard can veto a blank pointerdown

pointerdown consulted guard() only when the press hit a cell view, so nothing could suppress a blank interaction. That matters for DOM content rendered into paper.el — an overlay, a popup, a toolbar — where the paper cannot be reasoned with from outside: its listeners are delegated on paper.el, so a stopPropagation() from content inside it always arrives after the paper has already reacted.

Running the full guard() there is not an option — it rejects any target that is not inside the paper's own SVG, so a ruler or gutter in paper.el would stop opening a blank interaction at all, and the whole gesture with it, since the document-level drag listeners are delegated from pointerdown.

So guard() is split:

• guardExplicit(evt, view) — decisions about this event: the right mouse button, the guard option, an evt.data.guarded flag. Returns boolean | undefined; undefined means nothing decided. The third state is required because guarded: false is an explicit allow that must beat the target tests.
• guard(evt, view) — unchanged: guardExplicit() first, then judge the target — tag name, view, whether it lies inside the paper's SVG.

A press that hit no cell view consults only guardExplicit(), so it opens a blank interaction exactly as before and options.guard can now veto it. GUARDED_TAG_NAMES still judges the target, so a <select> in an overlay is not treated differently — there is a test pinning that.

guard() also returns a real boolean now: evt.data.guarded is caller-set and was only ever tested against undefined, so a null or 0 used to propagate out of a method typed boolean.

2. fix(joint-react): keep portaled content from driving the paper

<Paper> children are portaled into paper.el but render outside its SVG, and a press on one must not drive the paper. joint-core has to leave that press alone (a plain dia.Paper consumer rendering into paper.el relies on it), so the strict behaviour lives in the joint-react preset, which overrides guardExplicit. It runs after the caller's own options.guard.

3. fix(joint-core, joint-react): a button inside a node can both click and drag

A <button> in a node body or a magnet could only ever be clicked, so there was no way to drag a node by a button inside it, or to start a link from a button in a magnet — the natural gesture when the magnet is a row with a control in it.

The block came from one flag answering two questions. Now two lists:

list	decides
FORM_CONTROL_TAG_NAMES	keep the browser's default action (no preventDefault) → native click and focus
PREVENT_INTERACTION_TAG_NAMES	block element move / link-from-magnet

Same members by default, so core behaviour is unchanged. joint-react's preset drops BUTTON from the second list only — FORM_CONTROL_TAG_NAMES is inherited untouched, so a button keeps its native default action and still takes focus on press. (Verified in Chrome: document.activeElement is the button after a click.)

To keep one gesture from being both, the preset's pointerup withholds the next native click once the pointer has travelled past clickThreshold. joint-core already withholds its own pointerclick at that point; the browser does not, because press and release share a target whenever the node follows the pointer — exactly what happens when an element is dragged by a button inside it.

4. fix(joint-core): tag lists are matched against the whole path

Both lists were tested against evt.target alone. The press target of <button><span>Save</span></button> is the SPAN, which is in neither list — so a button with an icon or a label span inside it behaved the opposite way round from a bare one: it lost its default action (no focus) and did start an element move. Confirmed on dev before fixing.

hasTagNameInPath() walks from the target up to the cell view, so a press anywhere inside a control counts as a press on the control. Note this is a behaviour change for anyone who was (accidentally) dragging a node by markup nested inside one of these controls.

Path matching also makes OPTION redundant — an <option> only exists inside a <select>, which is listed — so it is dropped from both lists. Covered by a test using <select multiple>, whose options render inline and do receive real presses.

The lists stay exact tagName matches rather than becoming closest() selectors, so all three tag-name options (including the pre-existing GUARDED_TAG_NAMES) keep one matching semantic, and the arrays do not quietly become CSS selector lists.

Story (joint-react)

Examples → Buttons In Magnets shows one control per list, both in a node body and inside a magnet:

• <button> — clicks and drags; its label sits in a <span>, so it also exercises the nested-target case
• <input> — keeps every gesture that stays inside it, selecting text rather than dragging
• <select> — guarded outright; the event never reaches the paper

Typing (joint-core)

Paper.Options['guard'] now declares view optional. It has always been called without a view from pointerclick, pointerdblclick, mouseover and the rest. Custom guards that dereference view will now fail to compile — that surfaces a latent bug rather than creating one.

Tests

• joint-core QUnit: 2084 pass, incl. the overlay press + guard veto, the <select> bit-exactness case, the two-list split, and a press inside a <button>
• joint-core test:ts and lint clean
• joint-react: 96 suites / 1032 tests pass, typecheck and lint clean
• The interaction behaviour was also driven end to end in Chrome: click counts; drag from the button (and from the span inside it) moves the element without counting; drag off a magnet button creates a link; drag from the input or the select creates nothing and moves nothing

Note for reviewers: joint-react's jest resolves @joint/core to packages/joint-core/dist/joint.min.js, so that suite only exercises core changes after a yarn dist.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refines JointJS paper interaction guarding so options.guard can veto blank-area pointerdown events (including DOM overlays inside paper.el), while also enabling joint-react’s preset to keep portaled overlay content inert and allow <button> inside nodes/magnets to both click and drag without double-firing clicks after a drag.

Changes:

• Split guard logic into guardExplicit() (event-level veto/allow) plus guard() (event-level + target checks), and apply guarding to blank pointerdowns.
• Split form-control handling into FORM_CONTROL_TAG_NAMES (preserve native default) vs PREVENT_INTERACTION_TAG_NAMES (block paper interactions), and match both lists across the target path (not just evt.target).
• joint-react preset: guard portaled overlay content, allow button-driven drags, and swallow the next native click after a moved gesture; add story + tests.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/joint-react/stories/examples/buttons-in-magnets/story.tsx	Adds Storybook entry showcasing button/input/select interactions in nodes/magnets.
packages/joint-react/stories/examples/buttons-in-magnets/code.tsx	Implements the example UI demonstrating click+drag behaviors and guarded controls.
packages/joint-react/src/presets/paper.ts	Extends Paper preset with guardExplicit override, button interaction changes, and native click swallowing after drags.
packages/joint-react/src/presets/tests/paper-button-interactions.test.tsx	Adds Jest coverage for “button can drag without clicking” vs “click without drag”.
packages/joint-react/src/hooks/use-markup.ts	Updates hook documentation for interaction patterns inside magnets.
packages/joint-react/src/hooks/tests/use-markup.test.tsx	Adjusts test formatting / lint disables related to React perf rules.
packages/joint-react/src/components/paper/tests/paper-html-content-events.test.tsx	Adds Jest coverage ensuring portaled overlay presses don’t start blank interactions and React events still fire.
packages/joint-core/types/dia.d.ts	Updates typings for optional view in guard, adds PREVENT_INTERACTION_TAG_NAMES, and guardExplicit.
packages/joint-core/test/ts/index.test.ts	Adds TS-level coverage for optional view in guard callback typing.
packages/joint-core/test/jointjs/paper.js	Adds QUnit coverage for overlay guarding, path-based tag matching, and list split behavior.
packages/joint-core/src/dia/Paper.mjs	Core implementation: guardExplicit, blank-pointerdown guarding, split tag lists, and path-based matching helper.

Suppressed comments (1)

packages/joint-react/stories/examples/buttons-in-magnets/code.tsx:218

• This block comment is inaccurate: MAGNET_COUNT is 3 and only the first magnet row contains a button (the others render a text field and a select). The comment should match the actual rendered content.

/** Card with two magnets, each containing a button. */
function MagnetButtonsNode({ name }: Readonly<Partial<NodeData>>) {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

packages/joint-react/src/presets/paper.ts:253

• The preset override of guard should accept an optional view to match joint-core’s updated signature (guard(evt, view?)). Keeping it required makes the override’s typing stricter than the base class and can mask blank/HTML-target call sites.

    guard(this: dia.Paper, event: dia.Event, view: dia.CellView) {
      return protectedProto.guard.call(this, event, view) || wheelGuard(event);
    },

packages/joint-react/src/presets/paper.ts:27

• dia.Paper#guard can be invoked with no resolved cell view (e.g. blank targets / delegated handlers). This preset’s ProtectedPaperPrototype.guard type still requires view, which makes the local typing stricter than the core API and can hide undefined/null call sites in this file.

This issue also appears on line 251 of the same file.

type ProtectedPaperPrototype = {
  readonly pointermove: (event: dia.Event) => void;
  readonly pointerup: (event: dia.Event) => void;
  readonly startListening: () => void;
  readonly guard: (event: dia.Event, view: dia.CellView) => boolean;
  readonly guardExplicit: (event: dia.Event, view?: dia.CellView) => boolean | undefined;
};