Skip to content

feat(dia.Paper): add focus and blur events; expose them as @joint/react Paper props - #3481

Open
kumilingus wants to merge 5 commits into
clientIO:devfrom
kumilingus:feat/paper-focus-events
Open

feat(dia.Paper): add focus and blur events; expose them as @joint/react Paper props#3481
kumilingus wants to merge 5 commits into
clientIO:devfrom
kumilingus:feat/paper-focus-events

Conversation

@kumilingus

@kumilingus kumilingus commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

Description

Adds focus/blur paper events with the cell: / element: / link: variants, following the mouseover/mouseout pattern (same guard, same findView resolution, cell:* fired before element:*/link:* via the view notify chain), and exposes them in @joint/react as Paper event props.

The paper events are driven by the bubbling focusin/focusout DOM events — plain focus/blur do not bubble and so cannot be delegated (the same reason React's own onFocus/onBlur use focusin/focusout under the hood). The event names describe what happened to the cell. normalizeEvent is not applied (nothing to normalize on focus events). No blank: variants — a focus event outside of a cell view carries no useful information.

Motivation

Making cells keyboard-focusable (tabindex on the root via attrs) is a common accessibility approach; reacting to the focus currently requires a native DOM listener on paper.el. With this change:

paper.on('element:focus', (elementView) => {
    // e.g. select the focused element
});

or in React:

<Paper onElementFocus={({ id }) => setSelection(id)} />

Changes

@joint/core

  • dia/Paper.mjsfocusin/focusout in the events hash + handlers
  • dia/CellView.mjs, dia/ElementView.mjs, dia/LinkView.mjsfocusin/focusout methods notifying the cell:/element:/link: focus/blur events
  • types/dia.d.ts — the 6 new event signatures
  • test/jointjs/paper.js — event order + no event outside of cell views (native bubbling FocusEvents; the test $.fn.trigger shim dispatches non-bubbling CustomEvents)
  • changeset (@joint/core: minor)

@joint/react

  • presets/paper.ts — the ReactPaper focusin .joint-cell delegation workaround is deleted; the core now emits cell:focus/cell:blur natively under the same names, so the existing onCellFocus/onCellBlur props keep working unchanged (no API break)
  • presets/paper-events.ts — new onElementFocus, onElementBlur, onLinkFocus and onLinkBlur props for the element:/link: variants
  • paper-focus-events.test.tsx — coverage for the element/link variants
  • changeset (@joint/react: minor)

The paper turns the (bubbling) native focusin/focusout DOM events into
cell:/element:/link:/blank: paper events, following the mouseover/
mouseout pattern — so applications can react to keyboard focus on
cells (e.g. focusable cells via the root tabindex attribute) without
binding native DOM listeners on the paper element.
A focus event outside of a cell view carries no useful information —
keep the API surface to the cell:/element:/link: variants.
@kumilingus
kumilingus force-pushed the feat/paper-focus-events branch from a02a8fe to b9a30b8 Compare August 24, 2026 20:57
@kumilingus
kumilingus changed the base branch from master to dev August 24, 2026 20:57
kumilingus and others added 2 commits August 26, 2026 17:59
…blur

The paper events are driven by the bubbling focusin/focusout DOM events
(plain focus/blur do not bubble), but the cell:focus/cell:blur names
describe what happened to the cell — and match the naming @joint/react
already ships.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ement/link variants

The ReactPaper focusin/focusout delegation workaround is no longer
needed — dia.Paper now emits cell:focus/cell:blur natively under the
same names, so onCellFocus/onCellBlur keep working unchanged. Expose
the new element:/link: variants as onElementFocus, onElementBlur,
onLinkFocus and onLinkBlur.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kumilingus kumilingus changed the title feat(dia.Paper): add focusin and focusout events feat(dia.Paper): add focus and blur events; expose them as @joint/react Paper props Aug 26, 2026
onCellFocus/onCellBlur never shipped in a release (no changeset existed
for their addition), so the changelog entry covers the whole feature.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kumilingus
kumilingus requested a review from samuelgja August 26, 2026 16:10
kumilingus added a commit to kumilingus/joint that referenced this pull request Aug 26, 2026
Changesets were introduced after these commits landed on dev. Most of
the dev work was cherry-picked to master and released via the changeset
backfill there (clientIO#3467, v4.3.2-v4.3.5) — the only changes on dev absent
from any published release are the Map-backed cells container (clientIO#3423)
and the collection-accepting removeCells()/resetCells() (clientIO#3427). The
cell focus events from clientIO#3427 are excluded: their changeset lives on the
feat/paper-focus-events branch (clientIO#3481).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant