This is an automated email from the ASF dual-hosted git repository.
tiagobento pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-tools.git
The following commit(s) were added to refs/heads/main by this push:
new b0b3e2de028 NO-ISSUE: Improve READMEs and developer docs for BPMN and
DMN Editors package hierarchy (#3464)
b0b3e2de028 is described below
commit b0b3e2de0281681e310d54fbfaa565f21408777e
Author: Tiago Bento <[email protected]>
AuthorDate: Thu Feb 26 15:46:01 2026 -0500
NO-ISSUE: Improve READMEs and developer docs for BPMN and DMN Editors
package hierarchy (#3464)
Co-authored-by: Kbowers <[email protected]>
---
.../ci/patterns/non-source-files-patterns.txt | 1 -
.rat-excludes | 3 +
examples/bpmn-editor-on-webapp/README.md | 2 +-
examples/dmn-editor-on-webapp/README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 2 +-
.../README.md | 4 +-
.../README.md | 4 +-
.../README.md | 2 +-
.../README.md | 2 +-
packages/bpmn-editor-envelope/README.md | 12 +-
packages/bpmn-editor-envelope/docs/ARCHITECTURE.md | 5 +-
packages/bpmn-editor-envelope/docs/DEV.md | 4 +-
.../docs/{ARCHITECTURE.md => TESTS.md} | 4 +-
packages/bpmn-editor-standalone/README.md | 2 +-
.../bpmn-editor-standalone/docs/ARCHITECTURE.md | 6 +-
packages/bpmn-editor-standalone/docs/DEV.md | 9 +-
packages/bpmn-editor-standalone/docs/TEST.md | 18 ---
.../docs/TESTS.md} | 2 +
packages/bpmn-editor/README.md | 2 +-
packages/bpmn-editor/docs/ARCHITECTURE.md | 8 +-
packages/bpmn-editor/docs/DEV.md | 8 +-
packages/bpmn-editor/docs/TEST.md | 18 ---
.../ARCHITECTURE.md => bpmn-editor/docs/TESTS.md} | 2 +
.../bpmn-editor/docs/images/readme/hiring.bpmn.png | Bin 0 -> 179687 bytes
packages/bpmn-marshaller/README.md | 34 +++--
packages/bpmn-marshaller/tests/readme.test.ts | 53 ++++++++
packages/dmn-editor-envelope/README.md | 16 +--
.../docs/ARCHITECTURE.md | 5 +-
.../docs/DEV.md | 4 +-
.../docs/TESTS.md} | 4 +-
packages/dmn-editor-standalone/README.md | 2 +-
.../docs/ARCHITECTURE.md | 6 +-
.../docs/DEV.md | 9 +-
.../docs/TESTS.md} | 2 +
packages/dmn-editor/README.md | 34 ++++-
packages/dmn-editor/docs/ARCHITECTURE.md | 24 ++++
.../docs/DEV.md | 8 +-
.../docs/TEST.md => dmn-editor/docs/TESTS.md} | 2 +
.../images/readme/loan-pre-qualification.dmn.png | Bin 0 -> 109001 bytes
packages/dmn-marshaller/README.md | 37 ++++--
packages/dmn-marshaller/tests/readme.test.ts | 51 ++++++++
packages/editor/README.md | 18 +--
packages/envelope-bus/README.md | 139 ++++++++++++++++++++-
packages/envelope-bus/docs/ARCHITECTURE.md | 24 ++++
.../docs/DEV.md | 6 +-
.../ARCHITECTURE.md => envelope-bus/docs/TESTS.md} | 5 +-
packages/envelope-bus/tests/readme/readme.test.ts | 133 ++++++++++++++++++++
packages/envelope/README.md | 18 +--
packages/xml-parser-ts-codegen/README.md | 16 ++-
packages/xml-parser-ts/README.md | 64 ++++++++--
packages/xml-parser-ts/tests/readme.test.ts | 106 ++++++++++++++++
.../tests/schemas/my-schema-1.0/MySchema10.xsd | 18 +++
.../tests/schemas/my-schema-1.0/ts-gen/README.md} | 8 +-
.../tests/schemas/my-schema-1.0/ts-gen/meta.ts | 25 ++++
.../tests/schemas/my-schema-1.0/ts-gen/types.ts | 9 ++
packages/xyflow-react-kie-diagram/README.md | 16 +--
packages/xyflow-react-kie-diagram/docs/TEST.md | 18 ---
repo/MULTIPLYING_ARCHITECTURE.md | 27 ++++
64 files changed, 892 insertions(+), 183 deletions(-)
diff --git a/.github/supporting-files/ci/patterns/non-source-files-patterns.txt
b/.github/supporting-files/ci/patterns/non-source-files-patterns.txt
index 30dd7adc4b7..3663fa02500 100644
--- a/.github/supporting-files/ci/patterns/non-source-files-patterns.txt
+++ b/.github/supporting-files/ci/patterns/non-source-files-patterns.txt
@@ -1,4 +1,3 @@
-*.md
*.icns
*.ico
*.gif
diff --git a/.rat-excludes b/.rat-excludes
index 31d356316ca..ce8b4e08177 100644
--- a/.rat-excludes
+++ b/.rat-excludes
@@ -603,6 +603,9 @@
packages/xml-parser-ts-codegen/src/schemas/xsd-incomplete--manually-written/XSD.
packages/xml-parser-ts-codegen/src/schemas/xsd/HFP.xsd
packages/xml-parser-ts-codegen/src/schemas/xsd/XSD.xsd
packages/xml-parser-ts-codegen/src/schemas/xsd/xml.xsd
+packages/xml-parser-ts/tests/schemas/my-schema-1.0/MySchema10.xsd
+packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/meta.ts
+packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/types.ts
packages/yaml-language-server/tests/__snapshots__/YamlLanguageService.test.ts.snap
packages/yard-model/yard-model.iml
packages/yard-validator-worker/yard-validator-worker.iml
diff --git a/examples/bpmn-editor-on-webapp/README.md
b/examples/bpmn-editor-on-webapp/README.md
index 86ff021128f..cc1c026b4b7 100644
--- a/examples/bpmn-editor-on-webapp/README.md
+++ b/examples/bpmn-editor-on-webapp/README.md
@@ -17,7 +17,7 @@
# Example :: BPMN Editor on webapp
-This package contains a web application that features the BPMN Editor wrapped
inside a Micro-frontend Multiplying Architecture Envelope.
+This package contains a web application that features the BPMN Editor wrapped
inside a Micro-frontend [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) Envelope.
### Building the dependencies
diff --git a/examples/dmn-editor-on-webapp/README.md
b/examples/dmn-editor-on-webapp/README.md
index b3969a4aab2..efa3878fca0 100644
--- a/examples/dmn-editor-on-webapp/README.md
+++ b/examples/dmn-editor-on-webapp/README.md
@@ -17,7 +17,7 @@
# Example :: DMN Editor on webapp
-This package contains a web application that features the DMN Editor wrapped
inside a Micro-frontend Multiplying Architecture Envelope.
+This package contains a web application that features the DMN Editor wrapped
inside a Micro-frontend [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) Envelope.
### Building the dependencies
diff --git
a/examples/micro-frontends-multiplying-architecture-base64png-editor-chrome-extension/README.md
b/examples/micro-frontends-multiplying-architecture-base64png-editor-chrome-extension/README.md
index 001d1554635..d3a6869adf2 100644
---
a/examples/micro-frontends-multiplying-architecture-base64png-editor-chrome-extension/README.md
+++
b/examples/micro-frontends-multiplying-architecture-base64png-editor-chrome-extension/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Base64 PNG Editor
Chrome Extension
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Base64 PNG Editor
Chrome Extension
Allows seeing `.base64png` files directly in GitHub's website.
diff --git
a/examples/micro-frontends-multiplying-architecture-base64png-editor-on-webapp/README.md
b/examples/micro-frontends-multiplying-architecture-base64png-editor-on-webapp/README.md
index 66de02e7dd0..e3608c6b638 100644
---
a/examples/micro-frontends-multiplying-architecture-base64png-editor-on-webapp/README.md
+++
b/examples/micro-frontends-multiplying-architecture-base64png-editor-on-webapp/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Base64 PNG Editor on
webapp
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Base64 PNG Editor
on webapp
### Building the dependencies
diff --git
a/examples/micro-frontends-multiplying-architecture-base64png-editor-vscode-extension/README.md
b/examples/micro-frontends-multiplying-architecture-base64png-editor-vscode-extension/README.md
index 7c0b9ea3762..86a61747826 100644
---
a/examples/micro-frontends-multiplying-architecture-base64png-editor-vscode-extension/README.md
+++
b/examples/micro-frontends-multiplying-architecture-base64png-editor-vscode-extension/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Base64 PNG Editor VS
Code Extension
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Base64 PNG Editor
VS Code Extension
This package provides a VS Code Extension containing a Base64 PNG Editor,
which allows editing `.base64png` files.
diff --git
a/examples/micro-frontends-multiplying-architecture-base64png-editor/README.md
b/examples/micro-frontends-multiplying-architecture-base64png-editor/README.md
index 61208a2deb6..b94d6337d6c 100644
---
a/examples/micro-frontends-multiplying-architecture-base64png-editor/README.md
+++
b/examples/micro-frontends-multiplying-architecture-base64png-editor/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Base64 PNG Editor
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Base64 PNG Editor
This package is a Custom Editor made with React, which enables you to edit a
`.base64png` file.
diff --git
a/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-angular/README.md
b/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-angular/README.md
index 81936b0e708..fa4c488f1a2 100644
---
a/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-angular/README.md
+++
b/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-angular/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Ping-Pong View -
Angular implementation
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Ping-Pong View -
Angular implementation
The Ping-Pong View is an interface that components can implement to be used
inside a Ping-Pong View Envelope.
diff --git
a/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-react/README.md
b/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-react/README.md
index b7ab7f18730..cef56e43116 100644
---
a/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-react/README.md
+++
b/examples/micro-frontends-multiplying-architecture-ping-pong-view-in-react/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Ping-Pong View -
React implementation
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Ping-Pong View -
React implementation
The Ping-Pong View is an interface that components can implement to be used
inside a Ping-Pong View Envelope.
diff --git
a/examples/micro-frontends-multiplying-architecture-ping-pong-view/README.md
b/examples/micro-frontends-multiplying-architecture-ping-pong-view/README.md
index abe5947012e..968a150a011 100644
--- a/examples/micro-frontends-multiplying-architecture-ping-pong-view/README.md
+++ b/examples/micro-frontends-multiplying-architecture-ping-pong-view/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Ping-Pong View
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Ping-Pong View
This package exposes a library with the necessary files for you to create a
Ping-Pong View Envelope with your Ping-Pong View implementation.
diff --git
a/examples/micro-frontends-multiplying-architecture-ping-pong-views-on-webapp/README.md
b/examples/micro-frontends-multiplying-architecture-ping-pong-views-on-webapp/README.md
index fb4676ee0d3..637bbd366fe 100644
---
a/examples/micro-frontends-multiplying-architecture-ping-pong-views-on-webapp/README.md
+++
b/examples/micro-frontends-multiplying-architecture-ping-pong-views-on-webapp/README.md
@@ -15,9 +15,9 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: Ping-Pong Views on
webapp
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: Ping-Pong Views on
webapp
-This package contains a web application that features multiple ways of using
Ping-Pong Views wrapped inside Micro-frontends Multiplying Architecture
Envelopes, showcasing both Promises and Notifications features of Multiplying
Architecture Channel and Envelope APIs.
+This package contains a web application that features multiple ways of using
Ping-Pong Views wrapped inside Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) Envelopes, showcasing
both Promises and Notifications features of [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) Channel and Envelope
APIs.
### Building the dependencies
diff --git
a/examples/micro-frontends-multiplying-architecture-todo-list-view-on-webapp/README.md
b/examples/micro-frontends-multiplying-architecture-todo-list-view-on-webapp/README.md
index 1d45351bef1..e58cb59886f 100644
---
a/examples/micro-frontends-multiplying-architecture-todo-list-view-on-webapp/README.md
+++
b/examples/micro-frontends-multiplying-architecture-todo-list-view-on-webapp/README.md
@@ -15,9 +15,9 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: 'To do' List View on
webapp
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: 'To do' List View
on webapp
-This package contains a web application that features a 'To do' List View, a
simple component wrapped inside an Envelope with a simple API for manging 'To
do' items. It also features a very simple demo of Multiplying Architecture's
Shared value.
+This package contains a web application that features a 'To do' List View, a
simple component wrapped inside an Envelope with a simple API for manging 'To
do' items. It also features a very simple demo of [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md)'s Shared value.
### Building the dependencies
diff --git
a/examples/micro-frontends-multiplying-architecture-todo-list-view-vscode-extension/README.md
b/examples/micro-frontends-multiplying-architecture-todo-list-view-vscode-extension/README.md
index de4a96ec4d0..2a87ade1606 100644
---
a/examples/micro-frontends-multiplying-architecture-todo-list-view-vscode-extension/README.md
+++
b/examples/micro-frontends-multiplying-architecture-todo-list-view-vscode-extension/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: 'To do' List View VS
Code Extension
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: 'To do' List View
VS Code Extension
This package provides a VS Code Extension containing a 'To do' List View,
which can and the following commands:
diff --git
a/examples/micro-frontends-multiplying-architecture-todo-list-view/README.md
b/examples/micro-frontends-multiplying-architecture-todo-list-view/README.md
index 7944241e52d..c971aa557a9 100644
--- a/examples/micro-frontends-multiplying-architecture-todo-list-view/README.md
+++ b/examples/micro-frontends-multiplying-architecture-todo-list-view/README.md
@@ -15,7 +15,7 @@
under the License.
-->
-# Example :: Micro-frontends Multiplying Architecture :: 'To do' List View
+# Example :: Micro-frontends [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) :: 'To do' List View
This package exposes the necessary files for you to create a 'To do' List
Envelope.
diff --git a/packages/bpmn-editor-envelope/README.md
b/packages/bpmn-editor-envelope/README.md
index b9ac607524a..d2c52bfd845 100644
--- a/packages/bpmn-editor-envelope/README.md
+++ b/packages/bpmn-editor-envelope/README.md
@@ -17,14 +17,22 @@
## @kie-tools/bpmn-editor-envelope
-Package responsible for creating the necessary pumbling for
[@kie-tools/bpmn-editor](../bpmn-editor/README.md) to be used inside an
Envelope in Multiplying Architecture.
+Package responsible for creating the necessary plumbing for
[@kie-tools/bpmn-editor](../bpmn-editor/README.md) to be used inside an
**`Envelope`** in [Multiplying
Architecture](../envelope-bus/docs/ARCHITECTURE.md).
+
+### Features
+
+- Integration with external files for auto-filling DMN information in Business
Rule Tasks.
+- Support for Work Item Definition (`.wid`) files for registering Custom Tasks.
+- Keyboard Shortcuts for commands exposed by `<BpmnEditor>`'s imperative
handle.
+- Locale parameterization for internationalized labels.
+- State management for undo/redo stacks.
---
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
index 44984232b6f..0436efd00f2 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
@@ -15,4 +15,7 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor-envelope :: ARCHITECTURE
+
+- This package implements the `Editor` interface from `@kie-tools-core/editor`
for a BPMN Editor, making it compatible with editor definitions in
`@kie-tools/vscode-extensions` and `@kie-tools/online-editor`.
+- As the BPMN Editor API evolves to be more than just the `Editor` interface,
it features its own types specific for the BPMN Editorβ`BpmnEditorChannelApi`
and `BpmnEditorEnvelopeApi`.
diff --git a/packages/bpmn-editor-envelope/docs/DEV.md
b/packages/bpmn-editor-envelope/docs/DEV.md
index 44984232b6f..e5d92c09488 100644
--- a/packages/bpmn-editor-envelope/docs/DEV.md
+++ b/packages/bpmn-editor-envelope/docs/DEV.md
@@ -15,4 +15,6 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor-envelope :: DEV
+
+- Launch KIE Sandbox with the `--env live` flag for live-reloading to kick in
when you make changes to this package.
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/bpmn-editor-envelope/docs/TESTS.md
similarity index 85%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/bpmn-editor-envelope/docs/TESTS.md
index 44984232b6f..e262c584f33 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor-envelope/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor-envelope :: TESTS
+
+- Tests are done indirectly through KIE Sandbox and the BPMN Editor extension
for VS Code.
diff --git a/packages/bpmn-editor-standalone/README.md
b/packages/bpmn-editor-standalone/README.md
index 8e453a6e12d..9525413869a 100644
--- a/packages/bpmn-editor-standalone/README.md
+++ b/packages/bpmn-editor-standalone/README.md
@@ -80,7 +80,7 @@ The returned object will contain the methods needed to
manipulate the Editor:
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/bpmn-editor-standalone/docs/ARCHITECTURE.md
b/packages/bpmn-editor-standalone/docs/ARCHITECTURE.md
index 44984232b6f..12fb7b6ff51 100644
--- a/packages/bpmn-editor-standalone/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor-standalone/docs/ARCHITECTURE.md
@@ -15,4 +15,8 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor-standalone :: ARCHITECTURE
+
+- Webpack is used to bundle minified code which includes all CSS and assets
necessary for the BPMN Editor to render.
+- To avoid global object pollution and conflicts with the application's CSS,
the BPMN Editor will be loaded inside an `iframe`.
+- [**_Multiplying Architecture_** ](../../../repo/MULTIPLYING_ARCHITECTURE.md)
is used to wrap the BPMN Editor inside an **`Envelope`** and handle
communication with the `iframe`.
diff --git a/packages/bpmn-editor-standalone/docs/DEV.md
b/packages/bpmn-editor-standalone/docs/DEV.md
index 44984232b6f..a4438dd7933 100644
--- a/packages/bpmn-editor-standalone/docs/DEV.md
+++ b/packages/bpmn-editor-standalone/docs/DEV.md
@@ -15,4 +15,11 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor-standalone :: DEV
+
+- The development environment for the `BpmnEditor` global object is based on
Storybook, acting as a playground and a publishable self-documentation.
+- Simply run the following command and navigate to http://localhost:9904
+ ```shell
+ pnpm start
+ ```
+- An HTTP Server is run on http://localhost:9007 to serve the minified JS file
containing the BPMN Editor.
diff --git a/packages/bpmn-editor-standalone/docs/TEST.md
b/packages/bpmn-editor-standalone/docs/TEST.md
deleted file mode 100644
index 44984232b6f..00000000000
--- a/packages/bpmn-editor-standalone/docs/TEST.md
+++ /dev/null
@@ -1,18 +0,0 @@
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-// TODO
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/bpmn-editor-standalone/docs/TESTS.md
similarity index 94%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/bpmn-editor-standalone/docs/TESTS.md
index 44984232b6f..198fe60a8c7 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor-standalone/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
+# @kie-tools/bpmn-editor-standalone :: TESTS
+
// TODO
diff --git a/packages/bpmn-editor/README.md b/packages/bpmn-editor/README.md
index 6faee87cc7e..589d1b4718e 100644
--- a/packages/bpmn-editor/README.md
+++ b/packages/bpmn-editor/README.md
@@ -62,7 +62,7 @@ The Apache KIE BPMN Editor is built with
[Reactflow](https://reactflow.dev/) and
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/bpmn-editor/docs/ARCHITECTURE.md
b/packages/bpmn-editor/docs/ARCHITECTURE.md
index 44984232b6f..c28be16c936 100644
--- a/packages/bpmn-editor/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor/docs/ARCHITECTURE.md
@@ -15,4 +15,10 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor :: ARCHITECTURE
+
+- `<BpmnEditor>` is a regular Controlled Component, mainly controlled by the
`model` property.
+- The auto-generated `BPMN20__tDefinitions` type is used as the only
representation of the BPMN workflow.
+- Zustand and Immer are used to manage state, wrapped inside the
`useBpmnEditorStoreApi()` hook. Calling `bpmnEditorStoreApi.setState(...)` will
let you update any state, including the BPMN workflow.
+- Complicated operations done to the BPMN workflow are managed by mutations
inside the `mutations` directory.
+- The BPMN diagram is rendered by `@kie-tools/xyflow-react-kie-diagram`, which
uses ReactFlow.
diff --git a/packages/bpmn-editor/docs/DEV.md b/packages/bpmn-editor/docs/DEV.md
index 44984232b6f..d0868886edc 100644
--- a/packages/bpmn-editor/docs/DEV.md
+++ b/packages/bpmn-editor/docs/DEV.md
@@ -15,4 +15,10 @@
under the License.
-->
-// TODO
+# @kie-tools/bpmn-editor :: DEV
+
+- The development environment for the `<BpmnEditor>` component is based on
Storybook, acting as a playground and a publishable self-documentation.
+- Simply run the following command and navigate to http://localhost:9920
+ ```shell
+ pnpm start
+ ```
diff --git a/packages/bpmn-editor/docs/TEST.md
b/packages/bpmn-editor/docs/TEST.md
deleted file mode 100644
index 44984232b6f..00000000000
--- a/packages/bpmn-editor/docs/TEST.md
+++ /dev/null
@@ -1,18 +0,0 @@
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-// TODO
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/bpmn-editor/docs/TESTS.md
similarity index 95%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/bpmn-editor/docs/TESTS.md
index 44984232b6f..109b0d1cf39 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/bpmn-editor/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
+# @kie-tools/bpmn-editor :: TESTS
+
// TODO
diff --git a/packages/bpmn-editor/docs/images/readme/hiring.bpmn.png
b/packages/bpmn-editor/docs/images/readme/hiring.bpmn.png
new file mode 100644
index 00000000000..af8bcd1bdd0
Binary files /dev/null and
b/packages/bpmn-editor/docs/images/readme/hiring.bpmn.png differ
diff --git a/packages/bpmn-marshaller/README.md
b/packages/bpmn-marshaller/README.md
index 703976be103..c42907273ff 100644
--- a/packages/bpmn-marshaller/README.md
+++ b/packages/bpmn-marshaller/README.md
@@ -17,25 +17,43 @@
## @kie-tools/bpmn-marshaller
-A type-safe marshaller for XML <--> JSON conversation for BPMN models.
+A type-safe marshaller for XML <--> JSON conversation for BPMN workflows.
Features include:
+- Full compatibility with the BPMN 2.0.2 specification through the
specification's BPMN20 XSD files.
+- Out-of-the-box Drools extensions compatible with the jBPM Workflow Engine.
+- Auto-generated TypeScript type definitions for a JSON-friendly
representation of BPMN workflows (using
[`@kie-tools/xml-parser-ts-codegen`](../xml-parser-ts-codegen/)).
+
---
### Usage
----
+```ts
+import { BPMN20__tDefinitions } from
"@kie-tools/bpmn-marshaller/dist/schemas/bpmn-2_0/ts-gen/types";
+import { getMarshaller } from "@kie-tools/bpmn-marshaller";
-### Examples
+const marshaller = getMarshaller(`<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"; id="_bpmn_1"
targetNamespace="http://kie.apache.org/bpmn/_bpmn_1";>
+ <itemDefinition id="_foo_item_definition" structureRef="org.acme.Foo" />
+</definitions>
+`);
----
+// Parse from XML to JSON
+const json = marshaller.parser.parse();
+const bpmn: BPMN20__tDefinitions = json.definitions;
-## For development information see:
+// Modify
+bpmn.rootElement ??= [];
+bpmn.rootElement.push({
+ __$$element: "itemDefinition",
+ "@_id": "_bar_item_definition",
+ "@_structureRef": "org.acme.Bar",
+});
-- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
-- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+// Build from JSON to XML
+const xml = marshaller.builder.build(json);
+```
---
diff --git a/packages/bpmn-marshaller/tests/readme.test.ts
b/packages/bpmn-marshaller/tests/readme.test.ts
new file mode 100644
index 00000000000..806ec7fa561
--- /dev/null
+++ b/packages/bpmn-marshaller/tests/readme.test.ts
@@ -0,0 +1,53 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { getMarshaller } from "@kie-tools/bpmn-marshaller";
+import { BPMN20__tDefinitions } from
"@kie-tools/bpmn-marshaller/dist/schemas/bpmn-2_0/ts-gen/types";
+
+describe("readme", () => {
+ test("usage", () => {
+ const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"; id="_bpmn_1"
targetNamespace="http://kie.apache.org/bpmn/_bpmn_1";>
+ <itemDefinition id="_foo_item_definition" structureRef="org.acme.Foo" />
+</definitions>
+`;
+
+ const marshaller = getMarshaller(originalXml);
+ const json = marshaller.parser.parse();
+ const bpmn: BPMN20__tDefinitions = json.definitions;
+
+ bpmn.rootElement ??= [];
+ bpmn.rootElement.push({
+ __$$element: "itemDefinition",
+ "@_id": "_bar_item_definition",
+ "@_structureRef": "org.acme.Bar",
+ });
+
+ const xml = marshaller.builder.build(json);
+
+ expect(xml).toStrictEqual(`<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"; id="_bpmn_1"
targetNamespace="http://kie.apache.org/bpmn/_bpmn_1";
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI";
xmlns:dc="http://www.omg.org/spec/DD/20100524/DC";
xmlns:di="http://www.omg.org/spec/DD/20100524/DI";>
+ <itemDefinition id="_foo_item_definition" structureRef="org.acme.Foo" />
+ <itemDefinition id="_bar_item_definition" structureRef="org.acme.Bar" />
+</definitions>
+`);
+ });
+});
diff --git a/packages/dmn-editor-envelope/README.md
b/packages/dmn-editor-envelope/README.md
index 89d90b7bec7..ab26d344273 100644
--- a/packages/dmn-editor-envelope/README.md
+++ b/packages/dmn-editor-envelope/README.md
@@ -17,22 +17,22 @@
## DMN Editor Envelope
-Package responsible for creating the necessary pumbling for
[@kie-tools/dmn-editor](../dmn-editor/README.md) to be used inside an Envelope.
+Package responsible for creating the necessary pumbling for
[@kie-tools/dmn-editor](../dmn-editor/README.md) to be used inside an
**`Envelope`** in [Multiplying
Architecture](../envelope-bus/docs/ARCHITECTURE.md).
----
-
-### Usage
-
----
+### Features
-### Examples
+- Integration with external files for Included Models.
+- Keyboard Shortcuts for commands exposed by `<DmnEditor>`'s imperative handle.
+- Locale parameterization for internationalized labels.
+- State management for undo/redo stacks.
+- Bindings with DMN Editor's specific APIs such as importing Java classes.
---
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/xyflow-react-kie-diagram/docs/ARCHITECTURE.md
b/packages/dmn-editor-envelope/docs/ARCHITECTURE.md
similarity index 64%
rename from packages/xyflow-react-kie-diagram/docs/ARCHITECTURE.md
rename to packages/dmn-editor-envelope/docs/ARCHITECTURE.md
index 44984232b6f..2b758f087d3 100644
--- a/packages/xyflow-react-kie-diagram/docs/ARCHITECTURE.md
+++ b/packages/dmn-editor-envelope/docs/ARCHITECTURE.md
@@ -15,4 +15,7 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor-envelope :: ARCHITECTURE
+
+- This package implements the `Editor` interface from `@kie-tools-core/editor`
for a BPMN Editor, making it compatible with editor definitions in
`@kie-tools/vscode-extensions` and `@kie-tools/online-editor`.
+- The DMN Editor API evolved to be more than just the `Editor` interface,
featuring its own types specific for the DMN Editorβ`NewDmnEditorChannelApi`
and `NewDmnEditorEnvelopeApi`.
diff --git a/packages/xyflow-react-kie-diagram/docs/DEV.md
b/packages/dmn-editor-envelope/docs/DEV.md
similarity index 83%
rename from packages/xyflow-react-kie-diagram/docs/DEV.md
rename to packages/dmn-editor-envelope/docs/DEV.md
index 44984232b6f..ddb105a0c6f 100644
--- a/packages/xyflow-react-kie-diagram/docs/DEV.md
+++ b/packages/dmn-editor-envelope/docs/DEV.md
@@ -15,4 +15,6 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor-envelope :: DEV
+
+- Launch KIE Sandbox with the `--env live` flag for live-reloading to kick in
when you make changes to this package.
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/dmn-editor-envelope/docs/TESTS.md
similarity index 85%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/dmn-editor-envelope/docs/TESTS.md
index 44984232b6f..5a4a1bcccd7 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/dmn-editor-envelope/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor-envelope :: TESTS
+
+- Tests are done indirectly through KIE Sandbox and the DMN Editor extension
for VS Code.
diff --git a/packages/dmn-editor-standalone/README.md
b/packages/dmn-editor-standalone/README.md
index 106c31ca08a..42a87b1d991 100644
--- a/packages/dmn-editor-standalone/README.md
+++ b/packages/dmn-editor-standalone/README.md
@@ -80,7 +80,7 @@ The returned object will contain the methods needed to
manipulate the Editor:
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/dmn-editor-standalone/docs/ARCHITECTURE.md
similarity index 62%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/dmn-editor-standalone/docs/ARCHITECTURE.md
index 44984232b6f..1e2fed0fe81 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/dmn-editor-standalone/docs/ARCHITECTURE.md
@@ -15,4 +15,8 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor-standalone :: ARCHITECTURE
+
+- Webpack is used to bundle minified code which includes all CSS and assets
necessary for the DMN Editor to render.
+- To avoid global object pollution and conflicts with the application's CSS,
the DMN Editor will be loaded inside an `iframe`.
+- [**_Multiplying Architecture_** ](../../../repo/MULTIPLYING_ARCHITECTURE.md)
is used to wrap the DMN Editor inside an **`Envelope`** and handle
communication with the `iframe`.
diff --git a/packages/bpmn-editor-standalone/docs/DEV.md
b/packages/dmn-editor-standalone/docs/DEV.md
similarity index 66%
copy from packages/bpmn-editor-standalone/docs/DEV.md
copy to packages/dmn-editor-standalone/docs/DEV.md
index 44984232b6f..842e0916780 100644
--- a/packages/bpmn-editor-standalone/docs/DEV.md
+++ b/packages/dmn-editor-standalone/docs/DEV.md
@@ -15,4 +15,11 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor-standalone :: DEV
+
+- The development environment for the `DmnEditor` global object is based on
Storybook, acting as a playground and a publishable self-documentation.
+- Simply run the following command and navigate to http://localhost:9903
+ ```shell
+ pnpm start
+ ```
+- An HTTP Server is run on http://localhost:9006 to serve the minified JS file
containing the DMN Editor.
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/dmn-editor-standalone/docs/TESTS.md
similarity index 94%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/dmn-editor-standalone/docs/TESTS.md
index 44984232b6f..1a38756bee1 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/dmn-editor-standalone/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
+# @kie-tools/dmn-editor-standalone :: TESTS
+
// TODO
diff --git a/packages/dmn-editor/README.md b/packages/dmn-editor/README.md
index 3abd39d9fab..902746716b7 100644
--- a/packages/dmn-editor/README.md
+++ b/packages/dmn-editor/README.md
@@ -17,22 +17,50 @@
## @kie-tools/dmn-editor
-TODO: Description
+The Apache KIE DMN Editor.
+
+This package exposes the `<DmnEditor>` React component. Features include:
+
+- Support for the DMN 1.6 specification (minimum version is DMN 1.2)
+ - Files will automatically be converted to DMN 1.6 after a first
modification happens.
+- Best-effort backwards compatibility with the [Apache KIE DMN Editor
(classic)](https://www.npmjs.com/package/@kie-tools/kie-editors-standalone) β
no longer available (last available in Apache KIE 10.1).
+- Extension points compatible with the Drools DMN Engine and Kogito.
+ - Attachments
+ - Persistent widths on Boxed Expressions
+ - Constraint types (`range`, `expression`, `enumerated`)
+- Dedicated Data Types editor
+- Exporting the DMN diagram to SVG
+- Built in the "[Controlled
component](https://legacy.reactjs.org/docs/forms.html#controlled-components)"
pattern
+- Type-safe model representation (incl. extension points) powered by
[@kie-tools/dmn-marshaller](../dmn-marshaller/README.md)
+- Autolayout
+
+The Apache KIE DMN Editor is built with [Reactflow](https://reactflow.dev/)
and shares a lot of good qualities from the Apache KIE DMN Editor, like:
+
+- Grid snapping
+- Commands-based programmatic API (E.g., Binding to keyboard shortcuts)
+- Infinite canvas
+- Multi-node and edge selection
---
### Usage
+- Add the `<DmnEditor>` component to your React application; _or_
+- Use the Apache KIE DMN Editor as a standalone JavaScript/TypeScript library.
See [@kie-tools/dmn-editor-standalone](../dmn-editor-standalone/README.md).
+
---
-### Examples
+### Screenshots
+
+> 
+> A screenshot of a Loan Pre-qualification decision created with Apache KIE
DMN Editor
---
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/dmn-editor/docs/ARCHITECTURE.md
b/packages/dmn-editor/docs/ARCHITECTURE.md
new file mode 100644
index 00000000000..e10a1cbf1b4
--- /dev/null
+++ b/packages/dmn-editor/docs/ARCHITECTURE.md
@@ -0,0 +1,24 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# @kie-tools/dmn-editor :: ARCHITECTURE
+
+- `<DmnEditor>` is a regular Controlled Component, mainly controlled by the
`model` property.
+- The auto-generated `DMN_LATEST__tDefinitions` type is used as the only
representation of the DMN decision.
+- Zustand and Immer are used to manage state, wrapped inside the
`useDmnEditorStoreApi()` hook. Calling `dmnEditorStoreApi.setState(...)` will
let you update any state, including the DMN decision.
+- Complicated operations done to the DMN decision are managed by mutations
inside the `mutations` directory.
+- The DMN diagram is currently not rendered by
[`@kie-tools/xyflow-react-kie-diagram`](../../xyflow-react-kie-diagram/), which
uses ReactFlow, but rather uses its own diagram rendering internal framework
that gave origin to
[`@kie-tools/xyflow-react-kie-diagram`](../../xyflow-react-kie-diagram/).
diff --git a/packages/bpmn-editor-standalone/docs/DEV.md
b/packages/dmn-editor/docs/DEV.md
similarity index 74%
copy from packages/bpmn-editor-standalone/docs/DEV.md
copy to packages/dmn-editor/docs/DEV.md
index 44984232b6f..1df2188c1cf 100644
--- a/packages/bpmn-editor-standalone/docs/DEV.md
+++ b/packages/dmn-editor/docs/DEV.md
@@ -15,4 +15,10 @@
under the License.
-->
-// TODO
+# @kie-tools/dmn-editor :: DEV
+
+- The development envirionemnt for the `<DmnEditor>` component is based on
Storybook, acting as a playground and a publishable self-documentation.
+- Simply run the following command and navigate to http://localhost:9901
+ ```shell
+ pnpm start
+ ```
diff --git a/packages/bpmn-editor-envelope/docs/TEST.md
b/packages/dmn-editor/docs/TESTS.md
similarity index 95%
rename from packages/bpmn-editor-envelope/docs/TEST.md
rename to packages/dmn-editor/docs/TESTS.md
index 44984232b6f..5b8a52ba68d 100644
--- a/packages/bpmn-editor-envelope/docs/TEST.md
+++ b/packages/dmn-editor/docs/TESTS.md
@@ -15,4 +15,6 @@
under the License.
-->
+# @kie-tools/dmn-editor :: TESTS
+
// TODO
diff --git
a/packages/dmn-editor/docs/images/readme/loan-pre-qualification.dmn.png
b/packages/dmn-editor/docs/images/readme/loan-pre-qualification.dmn.png
new file mode 100644
index 00000000000..ec3d7dd8af6
Binary files /dev/null and
b/packages/dmn-editor/docs/images/readme/loan-pre-qualification.dmn.png differ
diff --git a/packages/dmn-marshaller/README.md
b/packages/dmn-marshaller/README.md
index 7e7969df027..cac3ccff43b 100644
--- a/packages/dmn-marshaller/README.md
+++ b/packages/dmn-marshaller/README.md
@@ -17,23 +17,44 @@
## @kie-tools/dmn-marshaller
-TODO: Description
+A type-safe marshaller for XML <--> JSON conversions for DMN decisions.
+
+Features include:
+
+- Full compatibility with the DMN 1.6 specification through the
specification's DMN16 XSD files.
+- Out-of-the-box KIE extensions compatible with the Drools DMN Engine.
+- Auto-genreated TypeScript type definitions for a JSON-friendly
representation of DMN decisions (using
[`@kie-tools/xml-parser-ts-codegen`](../xml-parser-ts-codegen/)).
---
### Usage
----
+```ts
+import { DMN_LATEST__tDefinitions, getMarshaller } from
"@kie-tools/dmn-marshaller";
-### Examples
+const marshaller = getMarshaller(
+ `<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20240513/MODEL/"; id="_dmn_1"
targetNamespace="http://kie.apache.org/dmn/_dmn_1";>
+ <itemDefinition id="_foo_item_definition" name="Foo" />
+</definitions>
+`,
+ { upgradeTo: "latest" }
+);
----
+// Parse from XML to JSON
+const json = marshaller.parser.parse();
+const dmn: DMN_LATEST__tDefinitions = json.definitions;
-## For development information see:
+// Modify
+dmn.itemDefinition ??= [];
+dmn.itemDefinition.push({
+ "@_id": "_bar_item_definition",
+ "@_name": "Bar",
+});
-- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
-- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+// Build from JSON to XML
+const xml = marshaller.builder.build(json);
+```
---
diff --git a/packages/dmn-marshaller/tests/readme.test.ts
b/packages/dmn-marshaller/tests/readme.test.ts
new file mode 100644
index 00000000000..913e16741f8
--- /dev/null
+++ b/packages/dmn-marshaller/tests/readme.test.ts
@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { DMN_LATEST__tDefinitions, getMarshaller } from
"@kie-tools/dmn-marshaller";
+
+describe("readme", () => {
+ test("usage", () => {
+ const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20240513/MODEL/"; id="_dmn_1"
targetNamespace="http://kie.apache.org/dmn/_dmn_1";>
+ <itemDefinition id="_foo_item_definition" name="Foo" />
+</definitions>
+`;
+
+ const marshaller = getMarshaller(originalXml, { upgradeTo: "latest" });
+ const json = marshaller.parser.parse();
+ const dmn: DMN_LATEST__tDefinitions = json.definitions;
+
+ dmn.itemDefinition ??= [];
+ dmn.itemDefinition.push({
+ "@_id": "_bar_item_definition",
+ "@_name": "Bar",
+ });
+
+ const xml = marshaller.builder.build(json);
+
+ expect(xml).toStrictEqual(`<?xml version="1.0" encoding="UTF-8" ?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20240513/MODEL/"; id="_dmn_1"
targetNamespace="http://kie.apache.org/dmn/_dmn_1";
xmlns:dmndi="https://www.omg.org/spec/DMN/20230324/DMNDI/";
xmlns:dc="http://www.omg.org/spec/DMN/20180521/DC/";
xmlns:di="http://www.omg.org/spec/DMN/20180521/DI/";
xmlns:kie="https://kie.org/dmn/extensions/1.0";>
+ <itemDefinition id="_foo_item_definition" name="Foo" />
+ <itemDefinition id="_bar_item_definition" name="Bar" />
+</definitions>
+`);
+ });
+});
diff --git a/packages/editor/README.md b/packages/editor/README.md
index 685c96bb8de..eec8774056d 100644
--- a/packages/editor/README.md
+++ b/packages/editor/README.md
@@ -17,23 +17,7 @@
## @kie-tools-core/editor
-Interfaces to define Editors.
-
----
-
-### Usage
-
----
-
-### Examples
-
----
-
-## For development information see:
-
-- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
-- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+Interfaces to define Editors as [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) **`Envelopes`**.
---
diff --git a/packages/envelope-bus/README.md b/packages/envelope-bus/README.md
index 7195bc9b681..d2a761f184e 100644
--- a/packages/envelope-bus/README.md
+++ b/packages/envelope-bus/README.md
@@ -15,24 +15,155 @@
under the License.
-->
-## @kie-tools-core/envelope-bus
+# @kie-tools-core/envelope-bus
-TODO: Description
+Enables components in different contexts to communicate between themselves
using a low-level `postMessage` method, inspired by
[Window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
in a type-safe way.
+
+Works with `iframe`s, Shared Workers, Electron apps, VS Code extensions, and
browser extensions.
+
+### Concepts
+
+- **`Channel`**: The main context (a.k.a. App Shell) which instantiates one or
many **`Envelopes`**.
+- **`Envelope`**: The wrapping layer containing a component that runs inside
an isolated sub-context.
+
+Communication between **`Channels`** and **`Envelopes`** is bi-directional,
and can be done in three ways:
+
+1. \***\*Notifications\*\***
+ - Simple method invocation with parameters. No response mechanism.
+1. \***\*Requests\*\***
+ - Like an async function call. Can send arguments and receive responses.
+1. \***\*Shared Values\*\***
+ - Values that exist in Channels and Envelopes at the same time. Kept in
sync via a publish/subscribe mechanism.
+
+One **`Channel`** can instantiate and communicate with multiple
**`Envelopes`**, but one **`Envelope`** can only communicate with the
**`Channel`** which instantiated it. (**`Channel`** --1..n--> **`Envelope`**)
+
+> This package can be understood as [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md)'s core, as components
wrapped inside an **`Envelope`** can be considered to be Micro-frontends, given
their well-defined APIs and isolated context.
---
### Usage
+Given two API definitions for a **`Channel`** and an **`Envelope`**:
+
+```ts
+import { SharedValueProvider } from "@kie-tools-core/envelope-bus/dist/api";
+
+interface ChannelApi {
+ setFoo(foo: string): void;
+ requestFoo(id: string): Promise<string>;
+ foo(): SharedValueProvider<string>;
+}
+
+interface EnvelopeApi {
+ init(origin: string): Promise<void>;
+ setBar(bar: string): void;
+ requestBar(id: string): Promise<string>;
+ bar(): SharedValueProvider<string>;
+}
+```
+
+#### @ Channel (E.g., main window, or App Shell)
+
+```ts
+import { EnvelopeServer } from "@kie-tools-core/envelope-bus/dist/channel";
+
+// Implement the Channel API.
+// This is provided by the Channel and consumed by the Envelope.
+const channelApiImpl: ChannelApi = {
+ setFoo: (foo) => {
+ console.log(`setFoo: ${foo}`);
+ },
+ requestFoo: async (id) => {
+ return `fooId: ${id}`;
+ },
+ foo: () => {
+ return { defaultValue: "default-foo" };
+ },
+};
+
+// Create an EnvelopeServer
+const envelopeServer = new EnvelopeServer<ChannelApi, EnvelopeApi>(
+ {
+ postMessage: (msg, targetOrigin) => {
+ iframe.contentWindow?.postMessage(msg, targetOrigin);
+ },
+ },
+ "my-origin",
+ (self) => self.envelopeApi.requests.init(self.origin) // This function is
called by `startInitPolling`
+);
+
+// Establish a connection with the Envelope
+envelopeServer.startInitPolling(channelApiImpl);
+
+// Once init polling finishes, you can start communicating with the Envelope by
+// sending Notifications
+envelopeServer.envelopeApi.notifications.setBar.send("bar");
+// making Requests
+envelopeServer.envelopeApi.requests.requestBar("1").then(console.log);
+// or updating a Shared Value
+envelopeServer.envelopeApi.shared.bar.set("bar");
+```
+
+> See [readme.test.ts](./tests/readme/readme.test.ts) for more details on
subscribing and unsubscribing to Notifications and Shared Value updates.
+
+#### @ Envelope (E.g., inside an iframe)
+
+```ts
+import { EnvelopeClient } from "@kie-tools-core/envelope-bus/dist/envelope";
+
+const envelopeApiImpl: EnvelopeApi = {
+ init: async (origin) => envelopeClient.associate(origin, envelopeServer.id),
+ setBar: jest.fn(),
+ requestBar: async (id) => `barId: ${id}`,
+ bar: () => ({ defaultValue: "default-bar" }),
+};
+
+const envelopeClient = new EnvelopeClient<EnvelopeApi, ChannelApi>({
+ postMessage: (msg, targetOrigin) => {
+ return window.parent.postMessage(msg, targetOrigin);
+ },
+});
+
+// Will start listening to "message" events in the window.
+// Now the Envelope can start receiving messages from the Channel.
+envelopeClient.startListening();
+
+// Once listening is turned on, you can start communicating with the Channel by
+// sending Notifications
+envelopeClient.channelApi.notifications.setFoo.send("foo");
+// making Requests
+envelopeClient.channelApi.requests.requestFoo("1");
+// or updating a Shared Value
+envelopeClient.channelApi.shared.foo.set("foo");
+
+// Will stop listening to "message" events in the window.
+envelopeClient.stopListening();
+```
+
+> See [readme.test.ts](./tests/readme/readme.test.ts) for more details on
subscribing and unsubscribing to Notifications and Shared Value updates.
+
+---
+
+### Usage in React
+
+- Refer to [`Hooks.ts`](./src/hooks/Hooks.ts) for some convenience Hooks for
easily using [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) concepts inside React
components and applications. Such as:
+
+- `useSharedValue`; and
+- `useSubscription`
+
---
-### Examples
+### References
+
+- [**US20230009811A1** - COMMUNICATION SYSTEM FOR MICRO-FRONTENDS OF A WEB
APPLICATION](https://patents.google.com/patent/US20230009811)
+- [**US20230297444A1** - SYNCHRONIZING VARIABLE VALUES BETWEEN AN APPLICATION
SHELL AND MICRO-FRONTENDS OF A WEB
APPLICATION](https://patents.google.com/patent/US20230297444)
---
## For development information see:
- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
+- π [TESTS.md](./docs/TESTS.md)
- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
---
diff --git a/packages/envelope-bus/docs/ARCHITECTURE.md
b/packages/envelope-bus/docs/ARCHITECTURE.md
new file mode 100644
index 00000000000..788fb271bf1
--- /dev/null
+++ b/packages/envelope-bus/docs/ARCHITECTURE.md
@@ -0,0 +1,24 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# @kie-tools-core/envelope-bus :: ARCHITECTURE
+
+- `channel/EnvelopeServer` and `envelope/EnvelopeClient` are simply convenient
abstractions on top of the `common/EnvelopeBusMessageManager`, where the entire
communication logic is.
+- Inter-**`Envelope`** notifications are possible through the **`Channel`**,
whenever **`Envelopes`** are subscribed to a message of the same type. This can
act as a broadcasting mechanism originating from **`Envelopes`**.
+- In order to make the definitions of APIs simple while providing a type-safe
consumption API, a Proxy mechanism is used to generate dynamic objects. See
`cachedProxy` usages in `common/EnvelopeBusMessageManager`.
+- Routing logic for incoming messages on both `channel/EnvelopeServer` and
`envelope/EnvelopeClient` are inside their `receive` method. Since
**`Channels`** can have multiple **`Envelopes`** of various types sending
messages to it through the same bus ("message" events on Window), a
sophisticated filtering mechanism exists.
+- It is possible to nest **`Envelope`**s, making an **`Envelope`** be both a
**`Channel`** and an **`Envelope`** at the same time.
diff --git a/packages/bpmn-editor-standalone/docs/DEV.md
b/packages/envelope-bus/docs/DEV.md
similarity index 77%
copy from packages/bpmn-editor-standalone/docs/DEV.md
copy to packages/envelope-bus/docs/DEV.md
index 44984232b6f..a3eaaaa2af4 100644
--- a/packages/bpmn-editor-standalone/docs/DEV.md
+++ b/packages/envelope-bus/docs/DEV.md
@@ -15,4 +15,8 @@
under the License.
-->
-// TODO
+# @kie-tools-core/envelope-bus :: DEV
+
+- Use Test-Driven Development (TDD).
+- When adding new features, always write a failing test first, then implement
the code to make it pass.
+- There are no development webapps for this package.
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/envelope-bus/docs/TESTS.md
similarity index 87%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/envelope-bus/docs/TESTS.md
index 44984232b6f..b19eb6878a1 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/envelope-bus/docs/TESTS.md
@@ -15,4 +15,7 @@
under the License.
-->
-// TODO
+# @kie-tools-core/envelope-bus :: TESTS
+
+- Unit tests are inside the `tests` folder
+- Run them with `pnpm jest`
diff --git a/packages/envelope-bus/tests/readme/readme.test.ts
b/packages/envelope-bus/tests/readme/readme.test.ts
new file mode 100644
index 00000000000..834f2edbb3b
--- /dev/null
+++ b/packages/envelope-bus/tests/readme/readme.test.ts
@@ -0,0 +1,133 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { EnvelopeServer } from "@kie-tools-core/envelope-bus/dist/channel";
+import { EnvelopeClient } from "@kie-tools-core/envelope-bus/dist/envelope";
+import { EnvelopeBusMessage } from "@kie-tools-core/envelope-bus/dist/api";
+import { SharedValueProvider } from "@kie-tools-core/envelope-bus/dist/api";
+
+interface ChannelApi {
+ setFoo(foo: string): void;
+ requestFoo(id: string): Promise<string>;
+ foo(): SharedValueProvider<string>;
+}
+
+interface EnvelopeApi {
+ init(origin: string): Promise<void>;
+ setBar(bar: string): void;
+ requestBar(id: string): Promise<string>;
+ bar(): SharedValueProvider<string>;
+}
+
+let channelApiImpl: ChannelApi;
+let envelopeApiImpl: EnvelopeApi;
+
+let envelopeServer: EnvelopeServer<ChannelApi, EnvelopeApi>;
+let envelopeClient: EnvelopeClient<EnvelopeApi, ChannelApi>;
+
+// Due to the direct-plug implementation of EnvelopeServer and EnvelopeClient,
all calls are synchronous.
+describe("readme", () => {
+ beforeEach(() => {
+ channelApiImpl = {
+ setFoo: jest.fn(),
+ requestFoo: async (id) => `fooId: ${id}`,
+ foo: () => ({ defaultValue: "default-foo" }),
+ };
+
+ envelopeApiImpl = {
+ init: async (origin) => envelopeClient.associate(origin,
envelopeServer.id),
+ setBar: jest.fn(),
+ requestBar: async (id) => `barId: ${id}`,
+ bar: () => ({ defaultValue: "default-bar" }),
+ };
+
+ envelopeClient = new EnvelopeClient<EnvelopeApi, ChannelApi>({
+ postMessage: (msg: EnvelopeBusMessage<any, any>, targetOrigin) => {
+ // Direct-plug. Normally this would've been something like
`window.parent.postMessage(msg, targetOrigin)`
+ return envelopeServer.receive(msg, channelApiImpl);
+ },
+ });
+
+ envelopeServer = new EnvelopeServer<ChannelApi, EnvelopeApi>(
+ {
+ postMessage: (msg: EnvelopeBusMessage<any, any>, targetOrigin) => {
+ // Direct-plug. Normally this would've been something like
`iframe.contentWindow?.postMessage(msg, targetOrigin)`
+ return envelopeClient.receive(msg, envelopeApiImpl);
+ },
+ },
+ "my-origin",
+ (self) => self.envelopeApi.requests.init(self.origin)
+ );
+
+ envelopeServer.startInitPolling(channelApiImpl);
+ expect(envelopeServer.initPolling).toStrictEqual(undefined);
+ });
+
+ //
+
+ test("channel -> envelope", async () => {
+ // notification
+ envelopeServer.envelopeApi.notifications.setBar.send("bar");
+ expect(envelopeApiImpl.setBar).toHaveBeenCalledTimes(1);
+ expect(envelopeApiImpl.setBar).toHaveBeenCalledWith("bar");
+
+ // request
+ const barId = await envelopeServer.envelopeApi.requests.requestBar("1");
+ expect(barId).toStrictEqual("barId: 1");
+
+ // default shared value
+ let barValue;
+ let barValueSubs = envelopeServer.envelopeApi.shared.bar.subscribe((bar)
=> (barValue = bar));
+ expect(barValue).toStrictEqual("default-bar");
+
+ // modified shared value
+ envelopeServer.envelopeApi.shared.bar.set("bar");
+ expect(barValue).toStrictEqual("bar");
+
+ // unsubscribed shared value
+ envelopeServer.envelopeApi.shared.bar.unsubscribe(barValueSubs);
+ envelopeServer.envelopeApi.shared.bar.set("bar-2");
+ expect(barValue).toStrictEqual("bar");
+ });
+
+ test("envelope -> channel", async () => {
+ // notification
+ envelopeClient.channelApi.notifications.setFoo.send("foo");
+ expect(channelApiImpl.setFoo).toHaveBeenCalledTimes(1);
+ expect(channelApiImpl.setFoo).toHaveBeenCalledWith("foo");
+
+ // request
+ const fooId = await envelopeClient.channelApi.requests.requestFoo("1");
+ expect(fooId).toStrictEqual("fooId: 1");
+
+ // default shared value
+ let fooValue;
+ let fooValueSubs = envelopeClient.channelApi.shared.foo.subscribe((foo) =>
(fooValue = foo));
+ expect(fooValue).toStrictEqual("default-foo");
+
+ // modified shared value
+ envelopeClient.channelApi.shared.foo.set("foo");
+ expect(fooValue).toStrictEqual("foo");
+
+ // unsubscribed shared value
+ envelopeClient.channelApi.shared.foo.unsubscribe(fooValueSubs);
+ envelopeClient.channelApi.shared.foo.set("foo-2");
+ expect(fooValue).toStrictEqual("foo");
+ });
+});
diff --git a/packages/envelope/README.md b/packages/envelope/README.md
index 60fe7d293ff..5e63966332b 100644
--- a/packages/envelope/README.md
+++ b/packages/envelope/README.md
@@ -17,23 +17,9 @@
## Envelope
-TODO: Description
+Thin wrapper around [**_Multiplying
Architecture_**](../../repo/MULTIPLYING_ARCHITECTURE.md) **`Envelopes`** adding
a "view" component for **`Envelopes`** rendering visual elements.
----
-
-### Usage
-
----
-
-### Examples
-
----
-
-## For development information see:
-
-- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
-- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+This package also allows **`Envelopes`** to be physically inside `div` or
`iframe` elements, for supporting Module Federation.
---
diff --git a/packages/xml-parser-ts-codegen/README.md
b/packages/xml-parser-ts-codegen/README.md
index c972f54006b..cff16e076cb 100644
--- a/packages/xml-parser-ts-codegen/README.md
+++ b/packages/xml-parser-ts-codegen/README.md
@@ -19,9 +19,9 @@
This package provides a Node.js script that generates TypeScript types and
metadata from XSD file(s) to parse/build XML strings from/to JSON using
`@kie-tools/xml-parser-ts`. It doesn't implement the entire XSD specification,
so there might be bugs when attempting to use it with an arbitrary XSD file.
-For more information about `@kie-tools/xml-parser-ts`, go to
[../packages/xml-parser-ts](../xml-parser-ts/README.md)
+For more information about `@kie-tools/xml-parser-ts`, go to
[@kie-tools/xml-parser-ts](../xml-parser-ts/README.md)
-It was created to provide a way to marshall/unmarshall BPMN, DMN, Test
Scenario, and PMML files, so it is only tested against those formats XSDs.
+This package was created to provide a way to marshall/unmarshall BPMN, DMN,
Test Scenario, and PMML files, so it is only tested against those formats XSDs.
> NOTE: This package is probably not suited for your use-case, as it is
> incomplete and was not tested with a large number of XSD files, but it
> should work for simple XSDs. If you want to use it, please go ahead! Let us
> know if you tried and it worked! Feel free to contribute too with issues and
> PRs too.
@@ -36,17 +36,23 @@ It was created to provide a way to marshall/unmarshall
BPMN, DMN, Test Scenario,
1. Supports multiple namespaces.
1. The generated types support extensions on types that contain `<xsd:any>`
and `<xsd:anyAttribute>`.
+### Conventions:
+
+1. Element attributes become `@_attrName` fields.
+1. Substitution groups use the `__$$element` property as a discriminator.
+1. Elements that accept text nodes will use the `__$$text` property to hold
its textual content.
+
### Usage:
`npx @kie-tools/xml-parser-ts-codegen relative/path/to/your-xsd-file.xsd
rootElementName`
-Types and metadata will be written to the same folder of `your-xsd-file.xsd`,
at the `ts-gen` directory. Two files are going to be generated:
+Types and metadata will be written to the same folder of `your-xsd-file.xsd`,
at the `./ts-gen` directory. Two files are going to be generated:
-1. types.ts
+1. `./ts-gen/types.ts`
- Contains the types representing the JSON obtained from parsing an XML
document.
- Extensible types are interfaces, so you can extend them with `declare
module ...`
- Hierarchies are flattened, to make it simple to extend the exact type
wanted.
-2. meta.ts
+2. `./ts-gen/meta.ts`
- `root`: Root element type and name
- `ns`: Bi-directional Namespace mapping created from the XSD file(s).
- `meta`: Type information to be used in runtime by
`@kie-tools/xml-parser-ts`. It's main use is to determine whetever an
element/attribute is a string/boolean/float/integer or an array, so the XMLs
are parsed and built consistently.
diff --git a/packages/xml-parser-ts/README.md b/packages/xml-parser-ts/README.md
index 493b1656336..c58fa8ab7d7 100644
--- a/packages/xml-parser-ts/README.md
+++ b/packages/xml-parser-ts/README.md
@@ -17,17 +17,65 @@
# @kie-tools/xml-parser-ts
-This lets you parse/build XML strings from/to JSON using types and metadata
generated with `@kie-tools/xml-parser-ts-codegen`. It uses DOMParser or `jsdom`
to parse the XMLs and guarantees that:
+This package lets you parse/build XML strings from/to JSON using types and
metadata generated with `@kie-tools/xml-parser-ts-codegen`, based on XSD
schemas. It uses DOMParser or `jsdom` to parse the XMLs and guarantees that:
-1. Parse/builds are idempotent for XMLs created with
-1. The JSON resulting from parsing is type-safe, as the metada generated by
`@kie-tools/xml-parser-ts-codegen` provides information on what is a string, a
boolean, an integer, a float or an array. Even if there's only one element on a
sequence, `@kie-tools/xml-parser-ts` will make sure it is an array with length
1.
-1. The types generated by `@kie-tools/xml-parser-ts-codegen` can be extended
and parsed/built.
-1. Unknown elements/attributes are kept in the original JSON.
-1. Comments ignored.
+- Parse/builds are idempotent after an initial normalizing parse.
+ - Namespaces declared on the original XML can be preserved when building
from the JSON.
+- The JSON resulting from parsing is type-safe, as the metadata generated by
`@kie-tools/xml-parser-ts-codegen` provides information on what is a string, a
boolean, an integer, a float, an array etc.
+ - Even if there's only one element on a sequence, `@kie-tools/xml-parser-ts`
will make sure it is an array with length 1.
+- The types generated by `@kie-tools/xml-parser-ts-codegen` can be extended
and parsed/built.
+- Unknown elements/attributes are kept in the original JSON.
+- Comments are ignored.
-### Some characteristics:
+### Usage:
-1. Namespaces declared on the original XML can be preserved when building from
the JSON.
+```ts
+import { getParser } from "@kie-tools/xml-parser-ts";
+
+// For a document of type "My Schema 1.0" which had its
+// type definitions generated with @kie-tools/xml-parser-ts-codegen
+import * as mySchema10 from "./schemas/my-schema-1.0/ts-gen/meta";
+import type { MySchema10__RootElementType } from
"./schemas/my-schema-1.0/ts-gen/types";
+
+// Create the parser dedicated to "My Schema 1.0".
+const mySchema10Parser = getParser<{ [mySchema10root.element]:
MySchema10__tRootElement }>(mySchema10);
+```
+
+```ts
+// Define a XML document.
+const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rootElement xmlns="https://kie.apache.org/my-schema-1.0"; version="1.0">
+ <childElement>Example child element content</childElement>
+</rootElement>
+`;
+
+// Parse it to JSON.
+const { json, instanceNs } = mySchema10Parser.parse({ type: "xml", xml:
originalXml });
+
+// Modify it.
+// NOTE: This is 100% type-safe, based on the generated types
+// created by @kie-tools/xml-parser-ts-codegen.
+json.rootElement["@_version"] = "1.1";
+// json.rootElement["@_version"] = 1 will not compile with "Type 'number' is
not assignable to type 'string'.ts(2322)"
+
+// Build an XML.
+// NOTE: `instanceNs` is used to maintain the same namespace
+// mapping as the original XML. You can also use
+// `mySchema10root.ns` to normalize it.
+const newXml = mySchema10Parser.build({ json, instanceNs });
+
+// Print the modified XML document.
+console.log(newXml);
+/**
+ * Output:
+ *
+ * <?xml version="1.0" encoding="UTF-8" ?>
+ * <rootElement xmlns="https://kie.apache.org/my-schema-1.0"; version="1.1">
+ * <childElement>Example child element content</childElement>
+ * </rootElement>
+ *
+ */
+```
---
diff --git a/packages/xml-parser-ts/tests/readme.test.ts
b/packages/xml-parser-ts/tests/readme.test.ts
new file mode 100644
index 00000000000..a4856583bf0
--- /dev/null
+++ b/packages/xml-parser-ts/tests/readme.test.ts
@@ -0,0 +1,106 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, foo 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { getParser } from "@kie-tools/xml-parser-ts";
+import * as mySchema10 from "./schemas/my-schema-1.0/ts-gen/meta";
+import type { MySchema10__RootElementType } from
"./schemas/my-schema-1.0/ts-gen/types";
+
+describe("my shema 1.0", () => {
+ test("basic usage", () => {
+ const myParser = getParser<{ [mySchema10.root.element]:
MySchema10__RootElementType }>(mySchema10);
+
+ const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rootElement xmlns="https://kie.apache.org/my-schema-1.0"; foo="1.0">
+ <childElement>Example child element content</childElement>
+</rootElement>
+`;
+
+ const { json, instanceNs } = myParser.parse({ type: "xml", xml:
originalXml });
+ expect(json).toEqual({
+ rootElement: {
+ "@_foo": "1.0",
+ "@_xmlns": "https://kie.apache.org/my-schema-1.0";,
+ childElement: {
+ __$$text: "Example child element content",
+ },
+ },
+ });
+
+ const xml = myParser.build({ json, instanceNs });
+ expect(xml).toStrictEqual(originalXml);
+ });
+
+ test("ns instead of instanceNs", () => {
+ const myParser = getParser<{ [mySchema10.root.element]:
MySchema10__RootElementType }>(mySchema10);
+
+ const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<myschema:rootElement xmlns:myschema="https://kie.apache.org/my-schema-1.0";
foo="1.0">
+ <myschema:childElement>Example child element content</myschema:childElement>
+</myschema:rootElement>
+`;
+
+ const { json } = myParser.parse({ type: "xml", xml: originalXml });
+ expect(json).toEqual({
+ rootElement: {
+ "@_foo": "1.0",
+ "@_xmlns:myschema": "https://kie.apache.org/my-schema-1.0";,
+ childElement: {
+ __$$text: "Example child element content",
+ },
+ },
+ });
+
+ const xml = myParser.build({ json, instanceNs: mySchema10.ns });
+ expect(xml).toStrictEqual(`<?xml version="1.0" encoding="UTF-8" ?>
+<rootElement xmlns:myschema="https://kie.apache.org/my-schema-1.0"; foo="1.0"
xmlns="https://kie.apache.org/my-schema-1.0";>
+ <childElement>Example child element content</childElement>
+</rootElement>
+`);
+ });
+
+ test("modifying", () => {
+ const myParser = getParser<{ [mySchema10.root.element]:
MySchema10__RootElementType }>(mySchema10);
+
+ const originalXml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rootElement xmlns="https://kie.apache.org/my-schema-1.0"; foo="1.0">
+ <childElement>Example child element content</childElement>
+</rootElement>
+`;
+
+ const { json, instanceNs } = myParser.parse({ type: "xml", xml:
originalXml });
+ expect(json).toEqual({
+ rootElement: {
+ "@_foo": "1.0",
+ "@_xmlns": "https://kie.apache.org/my-schema-1.0";,
+ childElement: {
+ __$$text: "Example child element content",
+ },
+ },
+ });
+
+ json.rootElement["@_foo"] = "1.1";
+
+ const xml = myParser.build({ json, instanceNs });
+ expect(xml).toStrictEqual(`<?xml version="1.0" encoding="UTF-8" ?>
+<rootElement xmlns="https://kie.apache.org/my-schema-1.0"; foo="1.1">
+ <childElement>Example child element content</childElement>
+</rootElement>
+`);
+ });
+});
diff --git a/packages/xml-parser-ts/tests/schemas/my-schema-1.0/MySchema10.xsd
b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/MySchema10.xsd
new file mode 100644
index 00000000000..35297deefa6
--- /dev/null
+++ b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/MySchema10.xsd
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xsd:schema
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema";
+ targetNamespace="https://kie.apache.org/my-schema-1.0";
+ elementFormDefault="qualified"
+>
+ <!-- Root element definition -->
+ <xsd:element name="rootElement" type="RootElementType" />
+
+ <!-- Complex type for root element -->
+ <xsd:complexType name="RootElementType">
+ <xsd:sequence>
+ <xsd:element name="childElement" type="xsd:string" minOccurs="0" />
+ </xsd:sequence>
+ <xsd:attribute name="foo" type="xsd:string" use="optional" />
+ <xsd:attribute name="bar" type="xsd:integer" use="optional" />
+ </xsd:complexType>
+</xsd:schema>
diff --git a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/README.md
similarity index 63%
copy from packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
copy to packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/README.md
index 44984232b6f..9918c3e487b 100644
--- a/packages/bpmn-editor-envelope/docs/ARCHITECTURE.md
+++ b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/README.md
@@ -15,4 +15,10 @@
under the License.
-->
-// TODO
+This directory was auto-generated with the following command in the root
folder of the [`@kie-tools/xml-parser-ts`](../../../../../xml-parser-ts/)
package.
+
+```shell
+node ../xml-parser-ts-codegen/bin.js
./tests/schemas/my-schema-1.0/MySchema10.xsd rootElement
+```
+
+This process can't be automated due to the recursive nature of
[`@kie-tools/xml-parser-ts`](../../../../../xml-parser-ts/) and
[`@kie-tools/xml-parser-ts-codegen`](../../../../../xml-parser-ts-codegen/)
diff --git a/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/meta.ts
b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/meta.ts
new file mode 100644
index 00000000000..6deeadb05b1
--- /dev/null
+++ b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/meta.ts
@@ -0,0 +1,25 @@
+export const root = {
+ element: "rootElement",
+ type: "MySchema10__RootElementType",
+} as const;
+
+export const ns = new Map<string, string>([
+ ["https://kie.apache.org/my-schema-1.0";, ""],
+ ["", "https://kie.apache.org/my-schema-1.0";],
+]);
+
+export const subs = {
+ "": {},
+};
+
+export const elements = {
+ rootElement: "MySchema10__RootElementType",
+};
+
+export const meta = {
+ MySchema10__RootElementType: {
+ "@_foo": { type: "string", isArray: false, fromType:
"MySchema10__RootElementType", xsdType: "xsd:string" },
+ "@_bar": { type: "integer", isArray: false, fromType:
"MySchema10__RootElementType", xsdType: "xsd:integer" },
+ childElement: { type: "string", isArray: false, fromType:
"MySchema10__RootElementType", xsdType: "xsd:string" },
+ },
+} as const;
diff --git a/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/types.ts
b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/types.ts
new file mode 100644
index 00000000000..00a55e33ad4
--- /dev/null
+++ b/packages/xml-parser-ts/tests/schemas/my-schema-1.0/ts-gen/types.ts
@@ -0,0 +1,9 @@
+// This file was automatically generated
+
+import { XmlParserTsRootElementBaseType } from "@kie-tools/xml-parser-ts";
+
+export type MySchema10__RootElementType = XmlParserTsRootElementBaseType & {
+ "@_foo"?: string; // from type MySchema10__RootElementType @ MySchema10.xsd
+ "@_bar"?: number; // from type MySchema10__RootElementType @ MySchema10.xsd
+ childElement?: { __$$text: string }; // from type
MySchema10__RootElementType @ MySchema10.xsd
+};
diff --git a/packages/xyflow-react-kie-diagram/README.md
b/packages/xyflow-react-kie-diagram/README.md
index 96ae3d95523..bbc9a04e5ee 100644
--- a/packages/xyflow-react-kie-diagram/README.md
+++ b/packages/xyflow-react-kie-diagram/README.md
@@ -25,21 +25,7 @@ This package exposes React components and utility functions
aimed at creating vi
### Usage
-// TODO
-
----
-
-### Examples
-
-// TODO
-
----
-
-## For development information see:
-
-- π [DEV.md](./docs/DEV.md)
-- π [TEST.md](./docs/TEST.md)
-- π [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+Please see [`@kie-tools/bpmn-editor`](../bpmn-editor) as an example of usage.
---
diff --git a/packages/xyflow-react-kie-diagram/docs/TEST.md
b/packages/xyflow-react-kie-diagram/docs/TEST.md
deleted file mode 100644
index 44984232b6f..00000000000
--- a/packages/xyflow-react-kie-diagram/docs/TEST.md
+++ /dev/null
@@ -1,18 +0,0 @@
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-// TODO
diff --git a/repo/MULTIPLYING_ARCHITECTURE.md b/repo/MULTIPLYING_ARCHITECTURE.md
new file mode 100644
index 00000000000..874cebb28a6
--- /dev/null
+++ b/repo/MULTIPLYING_ARCHITECTURE.md
@@ -0,0 +1,27 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# KIE Tools :: Multiplying Architecture
+
+- **_Multiplying Architecture_** is a concept in Apache KIE Tools related to
micro-frontends and reuse of UI components in diverse contexts.
+- The [`@kie-tools/envelope-bus`](../packages/envelope-bus) package contains
the core of the **_Multiplying Architecture_**.
+- This technology was originally developed so that Apache KIE BPMN, DMN, and
SceSim Editors could run inside modern web apps and platforms even though its
technology stack, design system, and CSS styles were completely different and
conflicting with its containing web apps or platforms.
+- **_Multiplying Architecture_** is extensively used to enable communication
between custom editors in VS Code extensions with the extension's backend, and
for powering KIE Sandbox's File System and Git subsystems
([`@kie-tools-core/workspaces-git-fs`](../packages/workspaces-git-fs/)).
+- The term **_Multiplying Architecture_** was coined to signify the ability
this technology has of making UI components, independent of their tech stack,
available in _multiple_ places and platforms, also independent of their
technology stack.
+- Refer to [`@kie-tools/envelope-bus`'s
README](../packages/envelope-bus/README.md) for more concrete details of the
**_Multiplying Architecture_**.
+- Because it allowed Apache KIE BPMN, DMN, and SceSim Editors to be present in
_multiple_ "_distribution **`Channels`**_", the term **`Channel`** stuck,
although it might be confusing at first.
+- **`Envelope`** was simply a nicer way to refer to a wrapper.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
