feat: add accessibility and keyboard editing to the react BPMN editor

[samuelgja]

Brings the react BPMN editor to the same accessibility level as the data modeling and AI workflow builder demos, with the accessibilitychecker.org badge in the bottom-left corner, and makes the diagram itself editable from the keyboard. Along the way it repaints the diagram palette, lets the inspector edit a whole selection at once, and reorganises dnd/, actions/ and utils/ along what each of them is for.

Accessibility

• Accessible names for every icon-only control and aria-pressed on toggles (theme, minimap, fullscreen).
• Landmarks (header/main/aside) with a visually hidden h1; inspector heading order fixed.
• Keyboard stencil support: the arrows aim at a pool or a lane, Enter/Space drops the shape there and selects it. Pools/lanes go through the same semantics as a pointer drop, including undo — the placement is batched, so a pool no longer takes seven undo presses to remove and a lane six (the pointer drop was already atomic, because the stencil batches it).
• Keyboard-focusable canvas (role=application, visible focus ring); outlined keyboard highlight for menu/select items.
• Muted text tokens now clear WCAG AA 4.5:1 in both themes.
• Decorative surfaces hidden from AT; tooltips/file menu portaled inside their landmarks, file menu non-modal.
• New "Check accessibility" pill linking the page to the accessibilitychecker.org audit.

Keyboard editing

• The arrows navigate: a directional Tab, stepping to the nearest shape in the direction pressed, and scrolling to it only when it is not fully in view. With nothing selected they pan the paper as before. Movement moved to Shift and an arrow — one grid step, swimlanes excluded, boundary events sliding along their activity's border, and pools growing to keep containing what moved (the pool-grow logic is shared between the pointer-drag and keyboard paths). Plain arrows meaning "move" cost a keyboard user any way to get around the diagram, which Tab alone does in document order rather than in the direction they are looking.
• Navigation falls back when the direction is empty: a 90° cone first, then 180° from the side, so an arrow finds the shape beside it rather than nothing. Links are part of the walk — with one selected the arrows step on rather than panning the paper away from it.
• Alt and an arrow resize anything the free transform can — a pool, a lane, a group, a comment — growing from the far border and shrinking back, so the plain arrows are left to mean one thing. A lane resizes both ways: across the pool the size is its own, along the pool it is the pool's, since every lane spans it. Both go through changeSwimlaneSize(), the route the free transform takes for the same drag. A resized shape can outgrow its lane exactly as a moved one can leave it, so the pool grows either way.
• A group is never embedded, whichever way it is added. It is a BPMN artifact — nothing contains it, and it is meant to span pools and lanes — so Group.validateEmbedding() refuses, and the keyboard drop now asks rather than carrying its own copy of the placement. (An annotation does belong to a lane, and still does.)
• Shrinking a lane stops at its content rather than cutting through it. The constraint the free transform applies to the same border drag lives in its internal swimlaneMinSize(), which is not part of the widget's typed API, so this mirrors it from the public pool and lane methods it is built on (getMinimumLaneSize, getSwimlanePadding, getElementsBBox, getContentMargin). Keyboard and pointer stop at the same size — 352px for a lane with content, 62px for an empty one. At the limit the arrow is consumed instead of falling through to the paper scroller.
• Enter/F2 opens the inline label editor over the single selected cell (elements, links, pools and lanes), the keyboard equivalent of a double click. Focus returns to the canvas when the editor closes, so renaming and moving chain together.
• Escape now cancels the edit. The text was written to the cell on blur regardless of how the editor closed, and Escape closed it by blurring — so it saved the edit it was meant to discard. The closing key no longer reaches the document-level shortcuts either, where Enter would have reopened the editor it just closed and Escape would have cleared the selection.
• The shortcuts that act on the diagram (rename, move, delete) now require a focused canvas. They are bound on document, so they also fired while the stencil or the toolbar had the focus, where Enter drops a shape and the arrow keys move the roving focus.
• Cmd/Ctrl+Enter adds a lane beside the selection — appended to a selected pool, or inserted directly after a selected lane, a position a stencil drop cannot express. The target is explicit instead of whichever pool graph.getElements().find(isPool) returns first, and the new lane is selected so it can be named straight away (cmd+enter, enter, type, enter).
• Cmd/Ctrl+C, X and V drive the built-in clipboard (<Diagram clipboard>), bound by the app so the paste can finish the job and the keys get the same focused-canvas guard. A copy keeps its place: util.cloneCells() only remaps the embedding of parents that were copied too, so a task copied out of a swimlane pasted loose — the copy now records the parent it came from and the paste puts the clone back into it, growing the pool to fit.
• Copying a container takes its contents. A pool clones whole (its lanes and shapes are all in the copied set); a lane is inserted with pool.addSwimlane() rather than embedded, so the pool lays itself out again and the lane's shapes travel with it, landing below the lane it was copied from. Cutting a lane copies it instead of removing it, since a pool must keep a lane.
• A keyboard drop had no target, so it added the shape at the middle of the view with addCell() and left it outside every pool — a state validateUnembedding refuses for a drag, and one that exports with the task outside any participant. The palette now holds an explicit target that the arrows step, with the view following via scrollToElement(): up/down walk every lane in the diagram as one run (carrying into the next pool at the end of one), left/right skip a pool, and both cycle. For a lane the target is the gap between lanes, so it can be inserted anywhere in the stack rather than only appended.
• The target is shown while a palette button has the focus, reusing the effects a drag already shows — the lane highlight for a shape, the insertion line for a lane — and named through aria-describedby ("Adds to Customer, position 1 of 3"), since a highlight is no use to a screen reader. The aim is seeded from the selection and then from what is on screen: the canvas selection survives focus moving to the palette, so it is the one signal of where the user was working.
• Selecting a cell already moved the focus to it, but a cell selected as soon as it was added — from the stencil, a paste, cmd+enter — had no view yet, since the paper renders asynchronously, so the focus was silently dropped. requireView() renders it on demand, and the add → rename → move chain now works without tabbing back to the canvas.
• Cmd/Ctrl+Enter adds what fits beside the selection — a connected shape from a shape, a shape inside a lane, a lane inside a pool — and Cmd/Ctrl+Arrow does the same with the side chosen. Shift+Cmd/Ctrl+Enter links the selection to a shape or pool that already exists, or adds a lane when a lane is selected (a lane cannot be linked: its validateConnection() refuses).
• What is offered comes from the model rather than a second list. The connect targets are the shape's own halo handles, so an end event offers nothing to flow into; the link targets are whatever validateConnection() accepts, pools included, since a message flow runs between participants. Link types are resolved from the endpoints by prepareLinkReplacement().
• The shape list is portalled out of the paper and positioned in screen coordinates — inside it, it rode along with the canvas, including the scroll it triggers itself while previewing a target. It anchors to the shape it was opened from, except for a lane, whose rect spans the whole pool: that anchors to the point where the shape will land.
• Alt+Enter moves the focus to the inspector for the selected element or link, and Escape brings it back to the shape — the panel was reachable only by tabbing out of the canvas and through the toolbar.
• A toolbar button (or F1) opens a dialog listing every shortcut, grouped, with the modifier rendered as the platform expects — the bindings were otherwise undiscoverable. Focus returns to the button on close.

Editing a selection at once

• The inspector edited exactly one cell: selecting three tasks showed the empty state, and recolouring five shapes meant clicking each one. It now shows what the selection has in common — a shared value, or nothing selected where they differ, written as -- in a select.
• The fields work across shape types, which store the same colour in different places: fill is attrs/background/fill on a task but attrs/body/fill on a gateway, and a pool wears its colour on its header. Each colour field declares the role it paints (fill, outline, text, and the font roles), so a new shape says where its colour lives and nothing central needs editing.
• Connectors are their own section, since a link has a line and a label rather than a body — a mixed selection reads as "2 shapes / 3 connectors". Cmd+A is staged to match: elements first, then the links too when the elements are already selected.
• One swatch click recolours the whole selection in a single undo step, batched — an unbatched loop over five shapes would take five undo presses.

Appearance

• The diagram palette is repainted and its tokens are named for what they do (tint-a, ink, start, decision) rather than for a hue, so a repaint moves the colours without the names going stale. ink clears WCAG AA 4.5:1 on the surface and on either tint, and 3:1 on the paper.
• A shape's icon stays readable against its own body. The icon is an <image> with the colour baked into a data URI, so it cannot follow the theme the way a fill can — the library's #333333 disappeared on a dark body. The ink is now chosen per shape from the body's luminance, at birth and on every recolour, theme switch and diagram load, and kept off the undo stack with skipHistory since it is a consequence of an edit rather than one itself.
• The lane an element is about to be dropped into is visible again: the highlight was mixed from a token that sat 1.02:1 against a pale lane. Dashed links follow the theme, borders are drawn in a colour the inspector's picker actually offers (an unset-looking swatch otherwise), and a new lane is created big enough to hold a task with its margin.

Selection

• A selected connector is highlighted. The selection frames mask a shape's body and a link has none, so the class the frame list puts on each selected cell carries it: the invisible 10px wrapper path becomes a halo along the line, leaving the line its own colour.
• Links and elements can no longer be held in one selection — the order decided whether it worked at all, and no tool acts on both.
• A cherry-picked selection may span pools: scoping the selection to one pool is right for a rubber-band region, not for cmd-clicking two shapes deliberately. The translate is withheld for such a selection instead, which is the part that misbehaved.

Fixes

• The label editor edits plain text. It was a rich-text contenteditable, so pasting from a document carried the formatting into a BPMN label.

• A click on a palette item is separated from a drag, so clicking one no longer starts aiming, and the item keeps a visible focus ring while it does.

• The canvas focus ring is drawn in full: it was clipped on the right and bottom by the scrolling container.

• The stencil's drag paper is shown in the top layer. It declares popover="manual" but is never opened, so it stacked under the stencil container (clientIO/joint-plus#803); the app shows it and the workaround is marked for removal.

• A new neighbour placed beside a shape is blocked only by what shares its lane: another lane's shapes slid it past empty space, and a pool it would overlap occupies that ground whatever we do.

• A group is never embedded, and no longer wears the connector halo — it has a wrapper node of its own, so the rule is scoped to links.

• The shortcuts dialog's list takes the focus itself. It scrolls when the window is short, and a scrollable region no keyboard can reach holds content a keyboard user cannot read — the one violation the re-run of the audit turned up after the repaint.

Three issues came out of this work: #801 (<PaperScroller> drops HTML attributes), #803 (the drag paper is never shown as a popover) and #804 (a threshold-aware companion to startCellDrag).

Verified: axe-core 0 violations across UI states (default, selection, both inspector views, the bulk form, both themes, export dialog, open menu/tooltip, and the shortcuts dialog), Lighthouse accessibility 100, keyboard walkthrough, tsc + eslint + vite build clean. The keyboard work is covered by a 72-check Playwright walkthrough: rename open/save/cancel for elements, links and lanes; focus return; the stencil and toolbar focus guards; blur-still-saves; resizing both lane orientations with the pool reflow, the content limit (matched against the pointer drag) and undo; lane insert position, orientation and no-ops; single-step undo/redo for every stencil drop; copy/cut/paste including the preserved embedding (checked by dragging the pool and watching the copy follow), lane and pool copies with their contents, and the clipboard's behaviour on an empty selection; the stencil aim (stepping across pools, cycling, insertion position, the highlight matching where the shape lands, and focus following a new cell); the dialog's open/close paths; and the keyboard creation — the halo-sourced offers, link validity (an end event offering only cross-pool targets), pool-to-pool links, all four directions, the pool growing rather than clamping a neighbour, the list surviving a canvas scroll, and its dismissal on a stencil drag or click.

The appearance and selection work is covered by its own suites: the shared/differing/-- states across shape types and both sections (18 checks), fonts and sizes, the connector highlight and the masks that stay on shapes only (12), the inspector shortcut and focus return (9), directional navigation including the 180° fallback and links (20), the rebound arrows (5), icon contrast in both themes and after a diagram load (9), the first pool wrapping the content and a second one leaving it alone (7), the pointer drags for pools and lanes with their previews and invalid marks (11), the link picker's targets, ordering and validity (8), file import by drop for both formats (6), lane sizing (4), cross-pool drag (4) and neighbour placement (3).

Internals worth a look: createShape()/getShapeMeta() replace four copies of graph.getTypeConstructor(type)! and two casts for the palette metadata; getLabelText() moves onto the pool and lane classes (a lane falls back to its pool's name, since lanes are commonly unnamed); and isSwimlane() now narrows to the app's own classes as isPool() already did, via BpmnPool/BpmnSwimlane (the App* prefix said nothing about this editor).

The last few commits sort the modules by what they hold rather than what they grew from. dnd/ is the drag callbacks: each reads as a few named steps, with the SVG preview in effects/ beside the ghost and lane previews it matches, the pool geometry in utils/ and the placement in actions/ — dnd/pools.ts went from 334 lines to 53. actions/ holds commands the user invokes, so the graph-loading half of the file import moved in and the drag-listener wiring moved out into the effect that runs it. utils/ holds the queries: the pool and lane lookups the keyboard aiming needs, and the link targets a source accepts. Names that misdescribed their function are fixed in passing — checkSwimlaneDrop performs the drop, positionInSwimlane returns a point.