Typed mxGraph

mxGraph Typescript Declarations For Official mxGraph NPM Package.

Usage

1. Add mxgraph and @typed-mxgraph/typed-mxgraph dependencies to your project:

   npm:

    npm install --save mxgraph
    npm install --save-dev @typed-mxgraph/typed-mxgraph

   yarn:

   yarn add mxgraph
   yarn add --dev @typed-mxgraph/typed-mxgraph

2. Update tsconfig.json append node_modules/@typed-mxgraph to typeRoots:

   {
     "compilerOptions": {
       "target": "es5",
       "module": "commonjs",
       "esModuleInterop": true,
       "typeRoots": [
         "node_modules/@types",
         "node_modules/@typed-mxgraph"
       ]
     }
   }

3. Import mxGraph factory:

   import factory from 'mxgraph';
   
   const mx = factory({
     mxBasePath: '',
   });
   console.log(mx.mxClient.VERSION);

4. (optional) Create a helper to import mxgraph

   // src/mxgraph.ts
   import factory from 'mxgraph';
   
   declare global {
     interface Window {
       mxBasePath: string;
       mxLoadResources: boolean;
       mxForceIncludes: boolean;
       mxLoadStylesheets: boolean;
       mxResourceExtension: string;
     }
   }
   
   window.mxBasePath = 'assets/mxgraph';
   window.mxLoadResources = true;
   window.mxForceIncludes = false;
   window.mxLoadStylesheets = true;
   window.mxResourceExtension = '.txt';
   
   export default factory({
     // not working see https://github.com/jgraph/mxgraph/issues/479
     mxBasePath: 'assets/mxgraph',
   });

   // src/application.ts
   import mx from './mxgraph';                       // <- import values from factory()
   import type { mxGraph, mxGraphModel } from 'mxgraph';  // <- import types only, "import type" is a TypeScript 3.8+ syntax
   
   export class Application {
   
     constructor(container: HTMLElement) {
       if(mx.mxClient.isBrowserSupported()) {
         console.log('Yes! Yes!');
       }
   
       const graph: mxGraph = new mx.mxGraph(container);
       const model: mxGraphModel = graph.getModel();
       model.beginUpdate();
       try {
         graph.insertVertex(graph.getDefaultParent(), '', 'TEST', 0, 0, 100, 100);
       } finally {
         model.endUpdate();
       }
     }
   
   }

There a known issues is #50 the error message may look similar to

Uncaught TypeError: Cannot set properties of undefined (setting 'mxBasePath')

For detailed reasons, please refer to:

• #50 (comment)
• and #50 (comment)

Demos:

• https://github.com/typed-mxgraph/typed-mxgraph-example-bundled-with-rollup
• https://github.com/typed-mxgraph/typed-mxgraph-example-bundled-with-webpack

Implementation

Types have been initially created from mxGraph 4.1.0 by hand (1st hosting repository was mxgraph-type-definitions) and progressively updated when new mxgraph versions have been released.

The mxgraph lib is almost fully covered by types in this project. The issues you may encounter are

• API changes in recent mxgraph have not been reported. We haven't decided how we will manage this in the future, so for now, they are updated when user detect issues
• Function arguments types or 'mandatoriness' may not be accurate: even by reading the JS code, it is sometimes hard to figure out what is the correct type.
• Historically, we try to avoid any and use optional when we don't know.
• We expect user to provide feedbacks by creating GitHub issues and/or Pull Requests when they notice issue with the types.

Implementation Progress

The definitions target mxGraph 4.2.2. See the implementation status in the following table.

• progress: initial support
  • not yet: no support at all
  • partial: implementation started, but some classes/fields/methods are missing
  • completed: all classes/fields/methods should exist (fill an issue and/or provide a Pull Request if you detect an issue) but
    • TSDoc is not fully accurate
    • some type declaration may be wrong
• checked: a finest review has been conducted about TSDoc, mxGraph types used by functions/methods, fields, ...

Module	Progress	Checked
editor	partial	no
handler	completed	no
io	completed	no
layout	completed	no
model	completed	no
shape	completed	no
util	partial	no
view	partial	no
mxClient.d.ts	completed	no

Development

• converting mxGraph API documentation to TSDoc: see regexp conversion helpers

Publish

Now we use GitHub Actions to automatically publish npm package.

Here are the steps to publish:

1. Merge PR to master branch
2. On master branch exec npm version <minor | patch> to automatically modify the version number and generate tags
3. On master branch exec git push origin master --tags
4. Then wait for the github action complete

Also See

We are actively developing, if you want to be a contributor, please refer to the following links

• mxgraph-road-to-DefinitelyTyped
• jgraph/mxgraph#81
• DefinitelyTyped/DefinitelyTyped#5317