chore: improve the configuration to build the npm package (maxGraph#87)

Root and all package.json files
  - Fix license, version and authors
  - Remove the non-relevant .npmignore file at the project. It was designed for mxgraph, the whole directory structure
  changed, and we don't plan to publish the root package

`core` package
  - Generate type definition and javascript files for ESM output
    - dedicated folder for `esm` and `types` in the `dist` folder to clearly separate concerns
    - exported in the package.json
  - Add npm script for `npm pack` configuration
  - Drop the `postinstall` npm script that built the `core` bundle. It would have been run when the package is installed
  in dependent projects at dependencies install. And it would have failed as it tries to build the project from TypeScript
  sources that are not available in the npm package.

fix: ConstraintHandler now loads image as everywhere else in the code using `Client.imageBasePath`
Using import doesn't work as the image is not available in the npm package. It generated error like this in ViteJS
project:
Failed to resolve import "../../../images/point.gif" from "../core/dist/esm/view/handler/ConstraintHandler.js". Does the file exist?
This gif import had been introduced to make `Anchors.stories.js` retrieve the gif file. Configuring `imageBasePath` as
already done in other stories fixes the issue.

Don't export EditorCodec and StylesheetCodec as they generate errors.
This is a temporary solution to avoid error in dependent project (at least, with ViteJS projects).

Author: tbouffard

.github/workflows/build.yml

@@ -31,12 +31,22 @@ jobs:
       matrix:
         os: ['ubuntu-20.04', 'macos-11', 'windows-2019']
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Setup node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
-          node-version: '16'
-      - name: Install dependencies and build @maxgraph/core
+          node-version-file: '.nvmrc'
+      - name: Install dependencies
         run: npm install
-      - name: Generate TypeScript declaration files
+      - name: Build @maxgraph/core - umd
+        working-directory: packages/core
+        run: npm run build
+      - name: Build @maxgraph/core - esm
+        working-directory: packages/core
+        run: npm run generate-esm
+      - name: Generate @maxgraph/core types
+        working-directory: packages/core
         run: npm run generate-types
+      - name: Build ts-example
+        working-directory: packages/ts-example
+        run: npm run build

.gitignore

@@ -7,6 +7,7 @@ javascript/examples/**/dist
 *.iml
 dist
 package-lock.json
+*.tgz
 
 # dependencies
 /node_modules

.npmignore

@@ -0,0 +1 @@
+16

.nvmrc

@@ -32,7 +32,7 @@ Chrome, Edge, Firefox, Safari, Chromium based browsers (Brave, Opera, ....) for
 maxGraph is under active development. An alpha version will be released soon with the npm package once [licensing](#license)
 and [versioning](https://github.com/maxGraph/maxGraph/issues/92) issues have been resolved.
 
-In the meantime, you can test the project by running the [Storybook examples](#development).
+In the meantime, you can test the project by running the [Storybook examples](#development) or [build the npm package locally](#build-local-npm-package).
 
 
 ## <a id="license"></a> Transition to Apache 2.0 license
@@ -52,10 +52,11 @@ const container = <HTMLElement>document.getElementById('graph-container');
 // Disables the built-in context menu
 InternalEvent.disableContextMenu(container);
 
+const graph = new Graph(container);
+graph.setPanning(true); // Use mouse right button for panning
 // Gets the default parent for inserting new cells. This
 // is normally the first child of the root (ie. layer 0).
 const parent = graph.getDefaultParent();
-graph.setPanning(true); // Use mouse right button for panning
 
 // Adds cells to the model in a single step
 graph.batchUpdate(() => {
@@ -65,7 +66,7 @@ graph.batchUpdate(() => {
 });
 ```
 
-You will see something like in the following:
+You will see something like in the following _maxGraph panning_ demo:
 
 ![maxGraph panning demo](docs/maxgraph_demo.gif "maxGraph panning demo")
 
@@ -162,6 +163,12 @@ and select `@mxgraph/html`.
 Since both commands are in watch mode, so it's recommended to open two terminals and run them separately. When a file is saved from the core package, the html storybook will be automatically updated.
 
 
-### Building the npm package for local usage
+### <a id="build-local-npm-package"></a> Building the npm package for usage in external project
+
+Run
+- from the project root: `npm install`
+- then, from the `packages/core` folder: `npm pack`
+
+The `packages/core` folder or the generated `packages/core/maxgraph-core-***.tgz` file are now ready for use in an external project, using [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) or `npm install`.
 
-Will be documented soon.
+Examples of use can be found in this [repository].(https://github.com/tbouffard/maxgraph-integration-examples).

README.md

@@ -1,27 +1,21 @@
 {
   "name": "maxgraph",
-  "description": "max-graph is a fully client side JavaScript diagramming library that uses SVG and HTML for rendering.",
-  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "description": "maxGraph is a fully client side JavaScript diagramming library that uses SVG and HTML for rendering.",
   "homepage": "https://github.com/maxGraph/maxGraph",
-  "author": {
-    "name": "",
-    "email": ""
-  },
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/maxGraph/maxGraph"
   },
   "bugs": {
     "url": "https://github.com/maxGraph/maxGraph/issues"
   },
-  "main": "./javascript/dist/build.js",
   "scripts": {
     "dev": "node ./scripts/dev",
     "bootstrap": "lerna bootstrap --no-ci",
     "postinstall": "lerna bootstrap --no-ci",
-    "docs": "jsdoc -c jsdoc.json",
-    "generate-types": "lerna run generate-types"
+    "docs": "jsdoc -c jsdoc.json"
   },
   "devDependencies": {
     "@babel/core": "^7.16.0",
@@ -33,6 +27,7 @@
     "babel-loader": "^8.2.3",
     "better-docs": "^2.3.2",
     "css-loader": "^6.5.1",
+    "cross-env": "~7.0.3",
     "file-loader": "^6.2.0",
     "jsdoc": "^3.6.7",
     "lerna": "^4.0.0",
@@ -44,6 +39,5 @@
     "webpack": "^5.64.4",
     "webpack-cli": "^4.9.1",
     "webpack-merge": "^5.8.0"
-  },
-  "sideEffects": true
+  }
 }

package.json

@@ -1,23 +1,32 @@
 {
   "name": "@maxgraph/core",
-  "version": "1.0.0",
-  "description": "",
-  "module": "./src/index.ts",
-  "main": "./dist/maxgraph.js",
-  "types": "./dist/maxgraph.d.ts",
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "description": "maxGraph is a fully client side JavaScript diagramming library that uses SVG and HTML for rendering.",
+  "main": "dist/maxgraph.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
   "files": [
-    "./dist"
+    "dist"
   ],
+  "homepage": "https://github.com/maxGraph/maxGraph",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxGraph/maxGraph"
+  },
+  "bugs": {
+    "url": "https://github.com/maxGraph/maxGraph/issues"
+  },
   "scripts": {
     "dev": "webpack --watch --mode=development",
-    "build": "NODE_ENV=production webpack --mode=production",
-    "postinstall": "webpack --mode=development",
-    "generate-types": "tsc --emitDeclarationOnly"
+    "build": "cross-env NODE_ENV=production webpack --mode=production",
+    "generate-types": "tsc --emitDeclarationOnly",
+    "generate-esm": "tsc --emitDeclarationOnly false --declaration false --declarationDir null",
+    "prepack": "run-s generate-types generate-esm build"
   },
-  "author": "",
-  "license": "ISC",
   "devDependencies": {
-    "circular-dependency-plugin": "^5.2.2"
+    "circular-dependency-plugin": "^5.2.2",
+    "npm-run-all": "~4.1.5"
   },
   "sideEffects": true
 }

packages/core/index.d.ts

@@ -5,22 +5,9 @@
 
 class Client {
   /**
-   * Class: Client
-   *
-   * Bootstrapping mechanism for the mxGraph thin client. The production version
-   * of this file contains all code required to run the mxGraph thin client, as
-   * well as global constants to identify the browser and operating system in
-   * use. You may have to load chrome://global/content/contentAreaUtils.js in
-   * your page to disable certain security restrictions in Mozilla.
-   *
-   * Contains the current version of the mxGraph library. The strings that
-   * communicate versions of mxGraph use the following format.
-   *
-   * versionMajor.versionMinor.buildNumber.revisionNumber
-   *
-   * Current version is 4.2.2.
+   * Contains the current version of the maxGraph library.
    */
-  static VERSION = '4.2.2';
+  static VERSION = '0.1.0';
 
   /**
    * Optional global config variable to specify the extension of resource files.
@@ -37,7 +24,7 @@ class Client {
 
   static setResourceExtension = (value: string) => {
     Client.mxResourceExtension = value;
-    
+
     // Removes dependency with mxResources.
     // Client.mxResourceExtension can be used instead.
     // mxResources.extension = value;
@@ -143,7 +130,7 @@ class Client {
    * contains the assignment. Trailing slashes are automatically removed.
    */
   static imageBasePath = '.';
-  
+
   static setImageBasePath = (value: string) => {
     if (typeof value !== 'undefined' && value.length > 0) {
       // Adds a trailing slash if required
@@ -416,9 +403,9 @@ class Client {
    * @param id unique id for the link element to check if it already exists
    */
   static link = (
-    rel: string, 
-    href: string, 
-    doc: Document | null=null, 
+    rel: string,
+    href: string,
+    doc: Document | null=null,
     id: string | null=null
   ) => {
     doc = doc || document;

packages/core/package.json

@@ -24,7 +24,7 @@ import { NODETYPE } from '../util/Constants';
 import Translations from '../util/Translations';
 import MaxLog from '../gui/MaxLog';
 import Codec from '../serialization/Codec';
-import { DropHandler } from 'src/view/other/DragSource';
+import type { DropHandler } from '../view/other/DragSource';
 
 /**
  * Toolbar for the editor. This modifies the state of the graph
@@ -204,10 +204,10 @@ export class EditorToolbar {
    * @param funct - Optional JavaScript function that takes the {@link Editor} as the first and only argument that is executed after the mode has been selected.
    */
   addMode(
-    title: string, 
-    icon: string, 
-    mode: string, 
-    pressed: string | null=null, 
+    title: string,
+    icon: string,
+    mode: string,
+    pressed: string | null=null,
     funct: Function | null=null
   ): any {
     const clickHandler = () => {
@@ -238,11 +238,11 @@ export class EditorToolbar {
    * Default is true.
    */
   addPrototype(
-    title: string, 
-    icon: string, 
-    ptype: Function | Cell, 
-    pressed: string, 
-    insert: (editor: Editor, cell: Cell, me: MouseEvent, cellUnderMousePointer?: Cell | null) => void, 
+    title: string,
+    icon: string,
+    ptype: Function | Cell,
+    pressed: string,
+    insert: (editor: Editor, cell: Cell, me: MouseEvent, cellUnderMousePointer?: Cell | null) => void,
     toggle: boolean=true
   ): HTMLImageElement | HTMLButtonElement {
     // Creates a wrapper function that is in charge of constructing

packages/core/src/Client.ts

@@ -48,7 +48,11 @@ export { default as VisibleChange } from './view/undoable_changes/VisibleChange'
 
 export { EditorKeyHandler, EditorKeyHandlerCodec } from './editor/EditorKeyHandler';
 export { EditorPopupMenu, EditorPopupMenuCodec } from './editor/EditorPopupMenu';
-export { EditorToolbar, EditorToolbarCodec } from './editor/EditorToolbar';
+// TODO restore EditorToolbarCodec if needed
+// currently, the following error occurs when running vitejs build
+// [ERROR] No matching export in "../core/dist/esm/editor/EditorToolbar.js" for import "EditorToolbarCodec"
+// export { EditorToolbar, EditorToolbarCodec } from './editor/EditorToolbar';
+export { EditorToolbar } from './editor/EditorToolbar';
 export { Editor, EditorCodec } from './editor/Editor';
 
 export { default as CellHighlight } from './view/cell/CellHighlight';
@@ -156,7 +160,11 @@ export { default as Rectangle } from './view/geometry/Rectangle';
 export { default as EdgeStyle } from './view/style/EdgeStyle';
 export { default as Perimeter } from './view/style/Perimeter';
 export { default as StyleRegistry } from './view/style/StyleRegistry';
-export { Stylesheet, StylesheetCodec } from './view/style/Stylesheet';
+// TODO restore StylesheetCodec if needed
+// currently, the following error occurs when running vitejs build
+// [ERROR] No matching export in "../core/dist/esm/view/style/Stylesheet.js" for import "StylesheetCodec"
+// export { Stylesheet, StylesheetCodec } from './view/style/Stylesheet';
+export { Stylesheet } from './view/style/Stylesheet';
 
 export * as DomHelpers from './util/domHelpers';
 
@@ -200,3 +208,6 @@ export { default as CellArray } from './view/cell/CellArray';
 export { default as TemporaryCellStates } from './view/cell/TemporaryCellStates';
 export { default as ConnectionConstraint } from './view/other/ConnectionConstraint';
 export { default as Multiplicity } from './view/other/Multiplicity';
+
+// Ensure types are exported in the type definitions
+export * from './types';

packages/core/src/editor/EditorToolbar.ts

@@ -19,7 +19,7 @@ import Rectangle from '../view/geometry/Rectangle';
 import Cell from '../view/cell/Cell';
 import GraphDataModel from '../view/GraphDataModel';
 import CellArray from '../view/cell/CellArray';
-import { CellStateStyle, CellStyle, NumericCellStateStyleKeys } from 'src/types';
+import type { CellStateStyle, CellStyle, NumericCellStateStyleKeys } from '../types';
 
 /**
  * Removes the cursors from the style of the given DOM node and its

packages/core/src/index.ts

@@ -26,8 +26,6 @@ import ConnectionConstraint from '../other/ConnectionConstraint';
 import Point from '../geometry/Point';
 import Cell from '../cell/Cell';
 
-import pointImg from '../../../images/point.gif';
-
 /**
  * Handles constraints on connection targets. This class is in charge of
  * showing fixed points when the mouse is over a vertex and handles constraints
@@ -39,8 +37,7 @@ class ConstraintHandler {
   /**
    * {@link Image} to be used as the image for fixed connection points.
    */
-  // pointImage: mxImage;
-  pointImage = new Image(pointImg, 5, 5);
+  pointImage = new Image(`${Client.imageBasePath}/point.gif`, 5, 5);
 
   /**
    * Reference to the enclosing {@link mxGraph}.

packages/core/src/util/styleUtils.ts

@@ -9,7 +9,7 @@ import InternalEvent from '../event/InternalEvent';
 import Dictionary from '../../util/Dictionary';
 import { Graph } from '../Graph';
 import Point from '../geometry/Point';
-import { CellStyle } from 'src/types';
+import type { CellStyle } from '../../types';
 
 declare module '../Graph' {
   interface Graph {

packages/core/src/view/handler/ConstraintHandler.ts

@@ -3,7 +3,7 @@ import Geometry from '../geometry/Geometry';
 import { Graph } from '../Graph';
 import CellArray from '../cell/CellArray';
 import { mixInto } from '../../util/Utils';
-import { CellStyle } from 'src/types';
+import type { CellStyle } from '../../types';
 
 declare module '../Graph' {
   interface Graph {

packages/core/src/view/mixins/EdgeMixin.ts

@@ -3,15 +3,15 @@
     "baseUrl": ".",
     "allowSyntheticDefaultImports": true,
     "declaration": true,
-    "declarationDir": "./dist",
+    "declarationDir": "./dist/types",
     "declarationMap": false,
     "emitDeclarationOnly": true,
     "esModuleInterop": true,
     "isolatedModules": true,
     "module": "ES2020",
     "lib": ["dom"],
     "moduleResolution": "node",
-    "outDir": "./dist",
+    "outDir": "./dist/esm",
     "strict": true,
     "target": "ES2020",
     "skipLibCheck": false,