From 42b736622e4e52d4079407a7de025660e3255f95 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Mon, 14 Feb 2022 14:29:24 +0100 Subject: [PATCH 1/2] [FIX] Fix the type definitions In the npm package, the definitions were previously located in dist/src instead of in dist/. It also contained development/demo types in dist/dev. So, project integrating bpmn-visualization were unable to retrieve the types and got errors like TS7016: Could not find a declaration file for module 'bpmn-visualization' The issue was located in the rollup configuration that override the tsconfig file when building the npm package. The 'include' configuration was not correctly overridden, so we used the development values. This is now fixed and there is a new test that will prevent this from happening again. Some definition files previously referenced types or classes that were not defined. Such elements are marked as internal and strip from the definitions. So this was generating errors like TS1192 or TS2305 (mainly involving BpmnModel, Edge or Shape). There were some functions and classes that weren't marked as @internal and so created the broken references. To improve the usage of bpmn-visualization in TypeScript projects, the README now provides more information about the TypeScript support and how to use the lib in TS projects. --- README.md | 30 +++++++++++++++++++ rollup.config.js | 12 ++++---- src/component/mxgraph/BpmnRenderer.ts | 10 ++++--- src/component/mxgraph/GraphCellUpdater.ts | 3 ++ src/component/mxgraph/style/utils.ts | 3 +- src/component/parser/json/converter/utils.ts | 2 +- src/component/parser/json/warnings.ts | 2 +- .../registry/bpmn-elements-registry.ts | 3 ++ src/component/registry/bpmn-model-registry.ts | 6 ++++ test/bundles/bundles.test.ts | 11 +++---- tsconfig.bundle.json | 6 ++++ 11 files changed, 68 insertions(+), 20 deletions(-) create mode 100644 tsconfig.bundle.json diff --git a/README.md b/README.md index 05c293bbc9..d5b401154b 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,36 @@ You can set the BPMN content using one of the following ways: * Load it from an url, like this [example](https://github.com/process-analytics/bpmn-visualization-examples/blob/master/examples/display-bpmn-diagram/load-remote-bpmn-diagrams/index.html) * Load from your computer, like the [demo example](https://github.com/process-analytics/bpmn-visualization-examples/tree/master/examples/display-bpmn-diagram/load-local-bpmn-diagrams/index.html) +#### TypeScript Support + +`bpmn-visualization` provides type definitions, so the integration should work out of the box in TypeScript projects. + +Depending on the build system used by the TypeScript project, it may get the following type errors +- error TS2688: Cannot find type definition file for 'typed-mxgraph' +- error TS7016: Could not find a declaration file for module 'mxgraph' + +In this case, +- Install `@typed-mxgraph/typed-mxgraph` as devDependencies, for instance by running `npm i --save-dev @typed-mxgraph/typed-mxgraph@1.0.4` +- Declare the `typed-mxgraph` types in the `tsconfig.json` as in the following 👇 + +```json +{ + "compilerOptions": { + "typeRoots": [ + "node_modules/@types", + "node_modules/@typed-mxgraph" + ] + } +} +``` + +Alternatively, you can set `skipLibCheck` to `true` in the `tsconfig.json` file but this limits the definition checks . +For more details, see the [skipLibCheck documentation](https://www.typescriptlang.org/tsconfig#skipLibCheck). + +Advanced users that want to extend the `mxGraph` integration must configure `typed-mxgraph`. + +For more details, see the TypeScript projects in the [bpmn-visualization-examples repository](https://github.com/process-analytics/bpmn-visualization-examples/). + ### 💠 Browser usage diff --git a/rollup.config.js b/rollup.config.js index 058fb38ba0..2605ac3bcd 100644 --- a/rollup.config.js +++ b/rollup.config.js @@ -124,15 +124,17 @@ function typescriptPlugin() { const tsSourceMap = !demoMode && !buildBundles; // TODO logic duplicated with build selection const tsconfigOverride = { compilerOptions: { sourceMap: tsSourceMap, declaration: tsDeclarationFiles } }; + const options = { + typescript: require('typescript'), + tsconfigOverride: tsconfigOverride, + }; + // Ensure we only bundle production sources if (!devMode) { - tsconfigOverride.include = ['src/**/*']; + options.tsconfig = './tsconfig.bundle.json'; } - return typescript({ - typescript: require('typescript'), - tsconfigOverride: tsconfigOverride, - }); + return typescript(options); } function withMinification(plugins) { diff --git a/src/component/mxgraph/BpmnRenderer.ts b/src/component/mxgraph/BpmnRenderer.ts index 32d35c75b4..905540bd27 100644 --- a/src/component/mxgraph/BpmnRenderer.ts +++ b/src/component/mxgraph/BpmnRenderer.ts @@ -14,15 +14,14 @@ * limitations under the License. */ -import type Shape from '../../model/bpmn/internal/shape/Shape'; import type { Edge, Waypoint } from '../../model/bpmn/internal/edge/edge'; +import { MessageFlow } from '../../model/bpmn/internal/edge/flows'; +import type Shape from '../../model/bpmn/internal/shape/Shape'; import type ShapeBpmnElement from '../../model/bpmn/internal/shape/ShapeBpmnElement'; import type Bounds from '../../model/bpmn/internal/Bounds'; -import { ShapeUtil } from '../../model/bpmn/internal'; +import { MessageVisibleKind, ShapeUtil } from '../../model/bpmn/internal'; import CoordinatesTranslator from './renderer/CoordinatesTranslator'; import StyleComputer from './renderer/StyleComputer'; -import { MessageFlow } from '../../model/bpmn/internal/edge/flows'; -import { MessageVisibleKind } from '../../model/bpmn/internal/edge/kinds'; import type { BpmnGraph } from './BpmnGraph'; import type { LoadOptions } from '../options'; import type { RenderedModel } from '../registry/bpmn-model-registry'; @@ -148,6 +147,9 @@ export function newBpmnRenderer(graph: BpmnGraph): BpmnRenderer { return new BpmnRenderer(graph, new CoordinatesTranslator(graph), new StyleComputer()); } +/** + * @internal + */ export function messageFowIconId(messageFlowId: string): string { return `messageFlowIcon_of_${messageFlowId}`; } diff --git a/src/component/mxgraph/GraphCellUpdater.ts b/src/component/mxgraph/GraphCellUpdater.ts index 8346d19883..ee4f69d2d1 100644 --- a/src/component/mxgraph/GraphCellUpdater.ts +++ b/src/component/mxgraph/GraphCellUpdater.ts @@ -22,6 +22,9 @@ import { ensureIsArray } from '../helpers/array-utils'; import { OverlayConverter } from './overlay/OverlayConverter'; import { messageFowIconId } from './BpmnRenderer'; +/** + * @internal + */ export function newGraphCellUpdater(graph: BpmnGraph): GraphCellUpdater { return new GraphCellUpdater(graph, new OverlayConverter()); } diff --git a/src/component/mxgraph/style/utils.ts b/src/component/mxgraph/style/utils.ts index c7aadee382..1ac98f1204 100644 --- a/src/component/mxgraph/style/utils.ts +++ b/src/component/mxgraph/style/utils.ts @@ -14,9 +14,8 @@ * limitations under the License. */ -import type { GlobalTaskKind, ShapeBpmnSubProcessKind } from '../../../model/bpmn/internal'; +import type { GlobalTaskKind, MessageVisibleKind, ShapeBpmnSubProcessKind } from '../../../model/bpmn/internal'; import { ShapeBpmnEventBasedGatewayKind, ShapeBpmnEventDefinitionKind } from '../../../model/bpmn/internal'; -import type { MessageVisibleKind } from '../../../model/bpmn/internal/edge/kinds'; import { mxgraph } from '../initializer'; import { BpmnStyleIdentifier } from './identifiers'; diff --git a/src/component/parser/json/converter/utils.ts b/src/component/parser/json/converter/utils.ts index 90d4fe8347..ecb12233df 100644 --- a/src/component/parser/json/converter/utils.ts +++ b/src/component/parser/json/converter/utils.ts @@ -139,6 +139,6 @@ export class ConvertedElements { } } -export interface CategoryValueData { +interface CategoryValueData { value?: string; } diff --git a/src/component/parser/json/warnings.ts b/src/component/parser/json/warnings.ts index 5ed46d5575..97f9b1c907 100644 --- a/src/component/parser/json/warnings.ts +++ b/src/component/parser/json/warnings.ts @@ -15,7 +15,7 @@ */ import type { MessageDetails } from '../parsing-messages'; import { JsonParsingWarning } from '../parsing-messages'; -import type { ShapeBpmnElementKind } from '../../../model/bpmn/internal/shape'; +import type { ShapeBpmnElementKind } from '../../../model/bpmn/internal'; export class GroupUnknownCategoryValueWarning extends JsonParsingWarning { constructor(readonly groupBpmnElementId: string, readonly categoryValueRef: string) { diff --git a/src/component/registry/bpmn-elements-registry.ts b/src/component/registry/bpmn-elements-registry.ts index d5b9717293..e0af74df3d 100644 --- a/src/component/registry/bpmn-elements-registry.ts +++ b/src/component/registry/bpmn-elements-registry.ts @@ -25,6 +25,9 @@ import type { BpmnElement, Overlay } from './types'; import type { BpmnModelRegistry } from './bpmn-model-registry'; import type { BpmnElementKind } from '../../model/bpmn/internal'; +/** + * @internal + */ export function newBpmnElementsRegistry(bpmnModelRegistry: BpmnModelRegistry, graph: BpmnGraph): BpmnElementsRegistry { return new BpmnElementsRegistry(bpmnModelRegistry, new HtmlElementRegistry(new BpmnQuerySelectors(graph.container?.id)), new CssRegistry(), newGraphCellUpdater(graph)); } diff --git a/src/component/registry/bpmn-model-registry.ts b/src/component/registry/bpmn-model-registry.ts index 3b8eb32ad7..076e0dc948 100644 --- a/src/component/registry/bpmn-model-registry.ts +++ b/src/component/registry/bpmn-model-registry.ts @@ -21,6 +21,9 @@ import { ShapeBpmnMarkerKind, ShapeUtil } from '../../model/bpmn/internal'; import type { ShapeBpmnSubProcess } from '../../model/bpmn/internal/shape/ShapeBpmnElement'; import ShapeBpmnElement from '../../model/bpmn/internal/shape/ShapeBpmnElement'; +/** + * @internal + */ export class BpmnModelRegistry { private searchableModel: SearchableModel; private onLoadCallback: () => void; @@ -71,6 +74,9 @@ function toRenderedModel(bpmnModel: BpmnModel): RenderedModel { return { boundaryEvents: boundaryEvents, edges: bpmnModel.edges, lanes: bpmnModel.lanes, otherFlowNodes: otherFlowNodes, pools: bpmnModel.pools, subprocesses: subprocesses }; } +/** + * @internal + */ export interface RenderedModel { edges: Edge[]; boundaryEvents: Shape[]; diff --git a/test/bundles/bundles.test.ts b/test/bundles/bundles.test.ts index 2373e2f71d..bb3f8ef4e3 100644 --- a/test/bundles/bundles.test.ts +++ b/test/bundles/bundles.test.ts @@ -32,13 +32,10 @@ describe('bundles', () => { ${'bpmn-visualization.esm.min.js'} | ${'ESM minified'} ${'bpmn-visualization.js'} | ${'IIFE'} ${'bpmn-visualization.min.js'} | ${'IIFE minified'} - `( - '$bundleType', - // eslint-disable-next-line @typescript-eslint/no-unused-vars - ({ file, bundleType }) => { - expect(existsSync(resolve(bundlesDirectoryPath, file))).toBe(true); - }, - ); + ${'bpmn-visualization.d.ts'} | ${'Type definitions'} + `('$bundleType', ({ file }: { file: string }) => { + expect(existsSync(resolve(bundlesDirectoryPath, file))).toBe(true); + }); }); it('IIFE bundle - should generate BPMN Diagram SVG', async () => { diff --git a/tsconfig.bundle.json b/tsconfig.bundle.json new file mode 100644 index 0000000000..5cd2e875f6 --- /dev/null +++ b/tsconfig.bundle.json @@ -0,0 +1,6 @@ +{ + "extends": "./tsconfig", + "include": [ + "src/**/*" + ] +} From 11b454eadb35fa6afd293a06eec74e7607d3c9c7 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 15 Feb 2022 17:20:56 +0100 Subject: [PATCH 2/2] improve README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Souchet Céline <4921914+csouchet@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d5b401154b..dfad20786a 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ In this case, } ``` -Alternatively, you can set `skipLibCheck` to `true` in the `tsconfig.json` file but this limits the definition checks . +Alternatively, you can set `skipLibCheck` to `true` in the `tsconfig.json` file, but this limits the definition checks. For more details, see the [skipLibCheck documentation](https://www.typescriptlang.org/tsconfig#skipLibCheck). Advanced users that want to extend the `mxGraph` integration must configure `typed-mxgraph`.