feat!: improve tree-shaking by isolating SelectionCellsHandler dependencies - #823

Move the cell handler creation logic out of AbstractGraph into the SelectionCellsHandler plugin, where it is actually used.

AbstractGraph referenced VertexHandler, EdgeHandler, ElbowEdgeHandler and EdgeSegmentHandler directly, so every application bundled them even when it never selected a cell. They are now reachable only through the plugin, so applications that do not register SelectionCellsHandler (visualization only, for example) no longer pay for them.

Configuring the cell handlers

Customizing a handler used to require subclassing the graph. The plugin now exposes factory setters, so the same customization is done by composition, on the plugin instance:

// Before
class MyGraph extends Graph {
  override createVertexHandler(state: CellState): VertexHandler {
    return new MyVertexHandler(state);
  }
}

// After
const selectionCellsHandler = graph.getPlugin<SelectionCellsHandler>('SelectionCellsHandler')!;
selectionCellsHandler.setVertexHandlerFactory((state) => new MyVertexHandler(state));

The setters only affect handlers created after the call, so they must be called before the first selection occurs.

createHandler and createEdgeHandler remain as dispatch methods, on SelectionCellsHandler instead of AbstractGraph. Overriding the dispatch logic itself is still possible, by extending the plugin and passing the subclass in the plugins option.

Custom edge handlers by configuration only

Which EdgeHandler gets instantiated is driven by the handlerKind of the EdgeStyleMetaData registered in the EdgeStyleRegistry. Previously, only the three built-in kinds were served, and only by overriding the matching create* method. A custom kind can now be handled without subclassing anything:

EdgeStyleRegistry.add('myEdgeStyle', MyEdgeStyle, { handlerKind: 'my-kind' });
selectionCellsHandler.setEdgeHandlerFactory('my-kind', (state) => new MyEdgeHandler(state));

Edge styles whose kind has no registered factory fall back to the 'default' one, so a partial configuration stays functional.

Documentation

A new usage/cell-handlers.md page in the website documents what the vertex and edge handlers do, the global handler configuration objects, how the handler kind is chosen, and how to configure the factories. The edge-styles.md and plugins.md pages link to it.

Notes

Covers #762

Impact on the size of the examples

The now column comes from ./scripts/build-all-examples.bash run on this branch. The before column comes from #1126 for the TypeScript examples, which is the previous commit in main and recalibrated them for Vite 8, and from the v0.24.0 release notes for the JavaScript examples, which are unchanged since that release as they are built with webpack and were therefore not affected by the Vite 8 upgrade.

Only the without-defaults examples benefit, as they are the ones that do not register SelectionCellsHandler. The four other examples grow by 0.14 to 0.20 kB, which is the cost of the factory map and its setters now held by the plugin.

ts-example-without-defaults is the only example whose chunkSizeWarningLimit needs an update, from 300 to 221.

For reference, the first measurement in this PR, done on the 0.20.0 development version (commit 4bcc016), reported a 83.5 kB decrease, and the experiment in #449 had shown a potential decrease of 63-66 kB.

Additional measure: without subclasses of EdgeHandler

In the future (#890), we may provide a way to configure the EdgeHandler that are registered in the plugin to reduce the size of application that doesn't require them:

• no children 7-8 kB
• Elbow only: 5 kB
• Segment only: 0 kB. Segment extends Elbow so it is imported as well.

Remaining Tasks

• rebase on main
• migrate JS stories using the former code to TS
  • DragSource: refactor: migrate the DragSource story to TypeScript #860
  • FixedPoints: refactor: migrate the FixedPoints story to TypeScript #839
  • PortRefs: refactor(stories): migrate PortRefs to TypeScript #1129
  • Wires: refactor: fix most problems in the Wires story #893, also required by refactor!: move tooltip methods to TooltipHandler #640
• update stories that used the former code, at least:
  • AutoLayout
  • ContextIcons
  • DragSource
  • FixedPoints
  • Handles
  • Orthogonal
  • PortRefs
  • Stencils
  • Wires
• manually test all modified stories
• update changelog
• PR description: compare the former and new way to override edge handler implementations and how to add custom edge handlers by configuration only
• final measure of example sizes
• prepare RN: provide an example showing how to migrate from the old to the new way of configuring + how to configure new custom edge handlers. The story have been migrated so they can help

Summary by CodeRabbit

• Breaking Changes

  • Cell-handler creation and customization now belong to the Selection Cells Handler plugin rather than graph subclasses.
  • Added configurable factories for custom vertex and edge handlers, including edge-style-specific and global options.
  • Added public handler factory types and updated handler creation behavior.

• Documentation

  • Added comprehensive cell-handler configuration and migration guidance.
  • Documented edge-style handler selection and updated API usage guidance.

• Tests

  • Expanded coverage for handler creation, customization, lifecycle, replacement, gestures, and cleanup.