feat(joint-layout-elk): new package - ELK layout with container and port support

[Geliogabalus]

Summary

Introduces @joint/layout-elk, a new package that lays out JointJS graphs with the Eclipse Layout Kernel (ELK) through elkjs. The single entry point is the async layout({ graph, elements?, links? }, options?).

layout() runs once and does not keep the graph laid out. It converts the graph to an ELK graph, runs ELK, and writes the result back onto the graph: positions, container sizes, link vertices and anchors, and port and label positions. All of it is applied in a single graph batch (batchName, default 'layout'), and the batch is closed even if a callback throws.

What gets laid out

• Containers - embedded elements are laid out inside their parent at any nesting depth, and the parent is resized to fit them (elk.hierarchyHandling: INCLUDE_CHILDREN). A link is filed under the lowest common ancestor of its two ends. Edge coordinates come back graph-absolute (elk.json.edgeCoords: ROOT).
• Ports - elements with ports are exported with elk.portConstraints: FIXED_POS, so ports stay where JointJS's port layout places them and edges route to that spot. Override it per element (e.g. FIXED_SIDE) to let ELK move them. Port labels are sized through exportPortLabel.
• Link labels - laid out inline on their edge and written back as position.distance/offset. Each ELK label carries the index of its link label in its id, so the result goes back to the right label even when some labels are dropped from the layout.
• Selection and order - elements/links choose what is laid out (a link only if both its ends are). The order of each list is also the model order ELK sees.

Customization

• Export callbacks (exportElement, exportPort, exportPortLabel, exportLink, exportLinkLabel) receive the ELK draft this package computed for that element, port, link or label. Mutate it in place (e.g. its layoutOptions), or return false to drop it from the layout.
• Import callbacks (setElementAttributes, setPortAttributes, setLinkAttributes) replace the default set()/portProp() calls - e.g. to animate the result with transition().
• elkLayoutOptions are passed to ELK unmodified. The package ships TypeScript types for the slice of ELK's options it uses.
• The result includes the layout's bounding box (bbox) and the raw ELK result (elkGraph).

Main thread, Web Worker and aborting

• By default, ELK runs on the main thread - no setup, and it works anywhere: browsers, Node/SSR, tests and the UMD build. The main-thread copy of ELK (elkjs/lib/elk.bundled.js) is imported dynamically, so bundlers split it into its own chunk, loaded only by the first layout without an elk option.
• createWorkerElk(createWorker) returns an ELK instance running in a Web Worker the app starts, passed to layout() as elk. The worker script is published as @joint/layout-elk/worker, so elkjs resolves from this package rather than from the app:

  const elk = createWorkerElk(() => new Worker(new URL('@joint/layout-elk/worker', import.meta.url), { type: 'module' }));
  await layout({ graph }, { elk });

  • The worker starts on the first layout and is shared by every later one.
  • A crash rejects only the layout the worker was running; a new worker takes over the layouts still waiting.
  • A worker that fails to load rejects its layouts with an explicit error instead of silently falling back to the main thread.
  • terminate() stops the worker and rejects the layouts not settled yet.
  • The instance talks to ELK's worker script directly rather than through elkjs/lib/elk-api.js, which can neither cancel a layout nor settle one whose worker fails.
• signal aborts a layout: layout() rejects with the signal's reason and applies nothing to the graph. If a createWorkerElk() worker is running the aborted layout, the worker is terminated. Main-thread ELK, or any other elk instance, can't be stopped, so its result is only ignored.

The app starts the worker itself because how a worker script is located depends on the bundler. While this PR was in progress, the package started its own worker, and that needed a separate workaround for Vite's dev server, esbuild, absolute publicPaths, the UMD build and CSP. The README documents the setup for webpack 5 and Vite, and for running without a bundler.

@joint/core changes

layout-elk reads resolved link labels from the model, without a view:

• dia.Link - add getComputedLabel()/getComputedLabels(), which resolve a label against defaultLabel and the built-in default. This resolution moves out of LinkView into dia/link-labels.mjs, and LinkView and RotateLabel now use it.
• dia.Element type fixes - portProp(portId) / portProp(portId, object, opt) overloads, and PortLabelPositionType.

Examples

• layout-elk-ts - migrated to layout() (previously hand-rolled ELK export/import).
• layout-elk-default-ts (new) - layout() at its simplest: no callbacks, ELK on the main thread.
• layout-elk-containers-ports-ts (new) - nested containers, ports with labels, and a wrapped, width-restricted layout.
• layout-elk-flowchart-ts (new) - an interactive flowchart: add ports and steps, connect them, and reorder steps by dragging. A new layout aborts the one still running.
• layout-elk-rectpacking-ts (new) - ELK's rectpacking algorithm on folders and files, with toolbar options and an animated transition.

All examples except layout-elk-default-ts run ELK in a Web Worker via createWorkerElk().

Test plan

• yarn test in packages/joint-layout-elk - 49/49 passing, coverage thresholds met (100% functions). This covers:
  • containers, ports, link labels, selection and order
  • the export/import callbacks
  • batching
  • abort (main thread, worker, and a custom instance)
  • createWorkerElk() - shared worker, aborting a running or a waiting layout, crash, load failure, a worker that can't be started, terminate()
  • loading main-thread ELK again after it failed to load
• yarn lint in packages/joint-layout-elk - clean
• All five examples built with webpack 5 and loaded in headless Chrome from a sub-path. Each lays out every element. The worker examples load only the worker files, never the main-thread chunk. The default example runs on the main thread without starting a worker.
• createWorkerElk() setup checked in real builds:
  • new Worker(new URL('@joint/layout-elk/worker', import.meta.url), { type: 'module' }) - webpack 5, Vite dev server, Vite build
  • import ElkWorker from '@joint/layout-elk/worker?worker' - Vite dev server, Vite build
• yarn changeset status --since=upstream/master - @joint/layout-elk minor (new package, 4.3.0 → 4.4.0), @joint/core minor

🤖 Generated with Claude Code