refactor: export mxGraph objects directly instead of via mxgraph namespace (#3491)

Destructure mxGraph objects from the mxgraph factory export so internal
code imports them directly (e.g. `mxGraph`, `mxConstants`) rather than
accessing them through `mxgraph.mxGraph`, `mxgraph.mxConstants`.

This enables tree-shaking since bundlers can track individual named
imports, improves readability by removing the repetitive `mxgraph.`
prefix, and makes imports explicit about which mxGraph objects each
module actually depends on.

mxGraph is exported separately with an explicit `typeof` annotation to
work around api-extractor losing constructor type information during
.d.ts rollup, which caused TS2507 in downstream type checks.

Author: tbouffard

dev/ts/component/SvgExporter.ts

@@ -16,7 +16,7 @@ limitations under the License.
 
 import type { mxGraph, mxSvgCanvas2D as mxSvgCanvas2DType } from 'mxgraph';
 
-import { mxgraph, mxClient, mxConstants, mxSvgCanvas2D, mxUtils } from '../../../src/component/mxgraph/initializer';
+import { mxClient, mxConstants, mxImageExport, mxSvgCanvas2D, mxUtils } from '../../../src/component/mxgraph/initializer';
 
 interface SvgExportOptions {
   scale: number;
@@ -92,7 +92,7 @@ ${svgAsString}
 
     svgCanvas.scale(s);
 
-    const imgExport = new mxgraph.mxImageExport();
+    const imgExport = new mxImageExport();
     // FIXME only the first overlay is placed at the right position
     // overlays put on element of subprocess/call-activity are not placed correctly in svg export
     imgExport.includeOverlays = true;

src/component/mxgraph/BpmnCellRenderer.ts

@@ -15,14 +15,14 @@ limitations under the License.
 */
 
 import type { IconPainter } from './shape/render';
-import type { mxCellState, mxImageShape, mxShape } from 'mxgraph';
+import type { mxCellState, mxImageShape as mxImageShapeType, mxShape } from 'mxgraph';
 
-import { mxgraph, mxRectangle } from './initializer';
+import { mxCellRenderer, mxDictionary, mxImageShape, mxRectangle } from './initializer';
 import { CustomCellOverlay } from './overlay/custom-overlay';
 import { OverlayBadgeShape } from './overlay/shapes';
 import { overrideCreateSvgCanvas } from './shape/utils';
 
-export class BpmnCellRenderer extends mxgraph.mxCellRenderer {
+export class BpmnCellRenderer extends mxCellRenderer {
   constructor(private readonly iconPainter: IconPainter) {
     super();
   }
@@ -33,7 +33,7 @@ export class BpmnCellRenderer extends mxgraph.mxCellRenderer {
     let dict = null;
 
     if (overlays != null) {
-      dict = new mxgraph.mxDictionary<mxShape>();
+      dict = new mxDictionary<mxShape>();
 
       for (const currentOverlay of overlays) {
         const shape = state.overlays == null ? null : state.overlays.remove(currentOverlay);
@@ -48,16 +48,16 @@ export class BpmnCellRenderer extends mxgraph.mxCellRenderer {
         if (currentOverlay instanceof CustomCellOverlay) {
           overlayShape = new OverlayBadgeShape(currentOverlay.label, new mxRectangle(0, 0, 0, 0), currentOverlay.style);
         } else {
-          overlayShape = new mxgraph.mxImageShape(new mxRectangle(0, 0, 0, 0), currentOverlay.image.src);
-          (overlayShape as mxImageShape).preserveImageAspect = false;
+          overlayShape = new mxImageShape(new mxRectangle(0, 0, 0, 0), currentOverlay.image.src);
+          (overlayShape as mxImageShapeType).preserveImageAspect = false;
         }
         // END bpmn-visualization CUSTOMIZATION
 
         overlayShape.dialect = state.view.graph.dialect;
         overlayShape.overlay = currentOverlay;
 
         // The 'initializeOverlay' signature forces us to hardly cast the overlayShape
-        this.initializeOverlay(state, overlayShape as mxImageShape);
+        this.initializeOverlay(state, overlayShape as mxImageShapeType);
         this.installCellOverlayListeners(state, currentOverlay, overlayShape);
 
         if (currentOverlay.cursor != null) {

src/component/mxgraph/BpmnGraph.ts

@@ -15,10 +15,10 @@ limitations under the License.
 */
 
 import type { IconPainter } from './shape/render';
-import type { mxCellRenderer, mxCellState, mxGraphView, mxPoint } from 'mxgraph';
+import type { mxCellRenderer, mxCellState, mxGraphView as mxGraphViewType, mxPoint } from 'mxgraph';
 
 import { BpmnCellRenderer } from './BpmnCellRenderer';
-import { mxgraph } from './initializer';
+import { mxGraph, mxGraphView } from './initializer';
 
 /**
  * Temporary storage for iconPainter during BpmnGraph construction.
@@ -49,7 +49,7 @@ import { mxgraph } from './initializer';
  */
 let pendingIconPainter: IconPainter | undefined;
 
-export class BpmnGraph extends mxgraph.mxGraph {
+export class BpmnGraph extends mxGraph {
   /**
    * @internal
    */
@@ -72,7 +72,7 @@ export class BpmnGraph extends mxgraph.mxGraph {
   /**
    * @internal
    */
-  override createGraphView(): mxGraphView {
+  override createGraphView(): mxGraphViewType {
     return new BpmnGraphView(this);
   }
 
@@ -108,7 +108,7 @@ export class BpmnGraph extends mxgraph.mxGraph {
   }
 }
 
-class BpmnGraphView extends mxgraph.mxGraphView {
+class BpmnGraphView extends mxGraphView {
   override getFloatingTerminalPoint(edge: mxCellState, start: mxCellState, end: mxCellState, source: boolean): mxPoint {
     // some values may be null: the first and the last values are null prior computing floating terminal points
     const edgePoints = edge.absolutePoints.filter(Boolean);

src/component/mxgraph/config/register-style-definitions.ts

@@ -17,7 +17,7 @@ limitations under the License.
 import type { mxAbstractCanvas2D, mxCell, mxPoint, mxShape } from 'mxgraph';
 
 import { ShapeBpmnElementKind } from '../../../model/bpmn/internal';
-import { mxCellRenderer, mxgraph } from '../initializer';
+import { mxCellRenderer, mxMarker } from '../initializer';
 import {
   BusinessRuleTaskShape,
   CallActivityShape,
@@ -102,5 +102,5 @@ const dashMarkerFactory = (
 };
 
 export const registerEdgeMarkers = (): void => {
-  mxgraph.mxMarker.addMarker(MarkerIdentifier.ARROW_DASH, dashMarkerFactory);
+  mxMarker.addMarker(MarkerIdentifier.ARROW_DASH, dashMarkerFactory);
 };

src/component/mxgraph/initializer.ts

@@ -33,26 +33,34 @@ import factory, { type mxGraphExportObject } from 'mxgraph';
  */
 export const mxgraph = initialize();
 
-/** @internal */
-export const mxCellRenderer = mxgraph.mxCellRenderer;
-/** @internal */
-export const mxClient = mxgraph.mxClient;
-/** @internal */
-export const mxConstants = mxgraph.mxConstants;
-/** @internal */
-export const mxEvent = mxgraph.mxEvent;
-/** @internal */
-export const mxPerimeter = mxgraph.mxPerimeter;
-/** @internal */
-export const mxPoint = mxgraph.mxPoint;
-/** @internal */
-export const mxRectangle = mxgraph.mxRectangle;
-/** @internal */
-export const mxRectangleShape = mxgraph.mxRectangleShape;
-/** @internal */
-export const mxSvgCanvas2D = mxgraph.mxSvgCanvas2D;
-/** @internal */
-export const mxUtils = mxgraph.mxUtils;
+// Destructured exports for convenient access to mxGraph objects.
+// mxGraph is exported separately to preserve its constructor types in the api-extractor generated .d.ts (destructuring loses `typeof` during rollup).
+export const {
+  mxCellOverlay,
+  mxCellRenderer,
+  mxClient,
+  mxConnector,
+  mxConstants,
+  mxDictionary,
+  mxEllipse,
+  mxEvent,
+  mxGeometry, // at least used in tests
+  mxGraphView,
+  mxImageExport,
+  mxImageShape,
+  mxMarker,
+  mxPerimeter,
+  mxPoint,
+  mxRectangle,
+  mxRectangleShape,
+  mxRhombus,
+  mxSvgCanvas2D,
+  mxText,
+  mxUtils,
+} = mxgraph;
+
+// Declare the type, because api-extractor loses the `typeof` during rollup when destructuring (see comment above).
+export const mxGraph: typeof mxgraph.mxGraph = mxgraph.mxGraph;
 
 /** @internal */
 declare global {

src/component/mxgraph/overlay/custom-overlay.ts

@@ -17,7 +17,7 @@ limitations under the License.
 import type { OverlayStyle } from '../../registry';
 import type { mxCellState, mxPoint as mxPointType, mxRectangle as mxRectangleType } from 'mxgraph';
 
-import { mxgraph, mxConstants, mxPoint, mxRectangle } from '../initializer';
+import { mxCellOverlay, mxConstants, mxPoint, mxRectangle } from '../initializer';
 
 export type VerticalAlignType = 'bottom' | 'middle' | 'top';
 export type HorizontalAlignType = 'left' | 'center' | 'right';
@@ -34,7 +34,7 @@ export interface CustomCellOverlayPosition {
 
 export type CustomCellOverlayStyle = Required<OverlayStyle>;
 
-export class CustomCellOverlay extends mxgraph.mxCellOverlay {
+export class CustomCellOverlay extends mxCellOverlay {
   readonly style: CustomCellOverlayStyle;
 
   constructor(

src/component/mxgraph/overlay/shapes.ts

@@ -17,9 +17,9 @@ limitations under the License.
 import type { CustomCellOverlayStyle } from './custom-overlay';
 import type { mxRectangle } from 'mxgraph';
 
-import { mxgraph } from '../initializer';
+import { mxText } from '../initializer';
 
-export class OverlayBadgeShape extends mxgraph.mxText {
+export class OverlayBadgeShape extends mxText {
   constructor(value: string, bounds: mxRectangle, style: CustomCellOverlayStyle) {
     super(
       value,

src/component/mxgraph/shape/edges.ts

@@ -16,10 +16,10 @@ limitations under the License.
 
 import type { mxAbstractCanvas2D, mxPoint } from 'mxgraph';
 
-import { mxgraph, mxSvgCanvas2D, mxUtils } from '../initializer';
+import { mxConnector, mxSvgCanvas2D, mxUtils } from '../initializer';
 import { BpmnStyleIdentifier } from '../style';
 
-export class BpmnConnector extends mxgraph.mxConnector {
+export class BpmnConnector extends mxConnector {
   override paintEdgeShape(c: mxAbstractCanvas2D, pts: mxPoint[]): void {
     // The indirection via functions for markers is needed in
     // order to apply the offsets before painting the line and

src/component/mxgraph/shape/event-shapes.ts

@@ -18,15 +18,15 @@ import type { BpmnCanvas, PaintParameter, IconPainter } from './render';
 import type { mxAbstractCanvas2D } from 'mxgraph';
 
 import { ShapeBpmnEventDefinitionKind } from '../../../model/bpmn/internal';
-import { mxgraph, mxUtils } from '../initializer';
+import { mxEllipse, mxUtils } from '../initializer';
 import { BpmnStyleIdentifier, StyleDefault } from '../style';
 
 import { buildPaintParameter } from './render/icon-painter';
 
 /**
  * @internal
  */
-export class EventShape extends mxgraph.mxEllipse {
+export class EventShape extends mxEllipse {
   // The actual value is injected at runtime by BpmnCellRenderer
   protected iconPainter: IconPainter = undefined;
 

src/component/mxgraph/shape/gateway-shapes.ts

@@ -18,13 +18,13 @@ import type { IconPainter, PaintParameter } from './render';
 import type { mxAbstractCanvas2D } from 'mxgraph';
 
 import { ShapeBpmnEventBasedGatewayKind } from '../../../model/bpmn/internal';
-import { mxgraph, mxUtils } from '../initializer';
+import { mxRhombus, mxUtils } from '../initializer';
 import { BpmnStyleIdentifier, StyleDefault } from '../style';
 import { getBpmnIsInstantiating } from '../style/utils';
 
 import { buildPaintParameter } from './render/icon-painter';
 
-abstract class GatewayShape extends mxgraph.mxRhombus {
+abstract class GatewayShape extends mxRhombus {
   // The actual value is injected at runtime by BpmnCellRenderer
   protected iconPainter: IconPainter = undefined;