Skip to content

Commit aad03e9

Browse files
jogibear9988jogibear9988
committed
first draft of a bpnm editor
0 parents  commit aad03e9

28 files changed

Lines changed: 7189 additions & 0 deletions

‎.github/workflows/deploy-pages.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deploy GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: github-pages
17+
cancel-in-progress: true
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
27+
- name: Setup Node.js
28+
uses: actions/setup-node@v4
29+
with:
30+
node-version: 20
31+
cache: npm
32+
33+
- name: Configure GitHub Pages
34+
uses: actions/configure-pages@v5
35+
36+
- name: Install dependencies
37+
run: npm ci
38+
39+
- name: Build Pages artifact
40+
run: npm run prepare-pages
41+
42+
- name: Upload Pages artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: site
46+
47+
deploy:
48+
needs: build
49+
runs-on: ubuntu-latest
50+
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/dist
2+
/node_modules
3+
/site

‎README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# BPMN Editor
2+
3+
This repository contains a browser-based BPMN XML editor built on top of `@node-projects/web-component-designer`. It combines a canvas editor, an XML code view, a BPMN-aware property grid, and a static deployment path that can be published directly to GitHub Pages.
4+
5+
The editor is aimed at lightweight BPMN authoring and diagram cleanup in the browser. It is not a workflow engine and it does not attempt to implement the full BPMN 2.0 execution model.
6+
7+
## Highlights
8+
9+
- Visual BPMN canvas with synchronized XML editing.
10+
- Palette-driven element creation for common BPMN nodes and edges.
11+
- BPMN-aware property editing for labels, documentation, event definitions, ids, references, and colors.
12+
- Context pad actions for delete, recolor, element replacement, and text-annotation creation.
13+
- Automatic rerouting of connected BPMN edges when nodes move or resize.
14+
- BPMN DI read and write support, including `bioc:fill` and `bioc:stroke` colors compatible with bpmn.io-style color metadata.
15+
- Collaboration-ready sample diagram with participants, lanes, message flow, group, annotation, and event definitions.
16+
- Drag-and-drop BPMN/XML loading, download/save-as support, and recent-document persistence in local storage.
17+
- Static GitHub Pages publishing through a generated `site/` artifact.
18+
19+
## Supported Surface
20+
21+
The current modeling surface focuses on the most useful diagramming elements for interactive editing:
22+
23+
- Events: start, intermediate catch, intermediate throw, boundary, end.
24+
- Activities: task, user task, service task, script task, manual task, business rule task, send task, receive task, call activity, sub process.
25+
- Gateways: exclusive, parallel, inclusive, event based.
26+
- Data and artifacts: data object, data store, text annotation, group.
27+
- Collaboration structures: participant and lane.
28+
- Edges: sequence flow, message flow, association, data input association, data output association.
29+
30+
## Local Development
31+
32+
### Prerequisites
33+
34+
- Node.js 18 or newer.
35+
- npm 9 or newer.
36+
37+
### Install and run
38+
39+
```bash
40+
npm ci
41+
npm start
42+
```
43+
44+
The dev server serves the project directly from the repository root. The app shell lives in `index.html`, while TypeScript sources compile into `dist/`.
45+
46+
### Useful scripts
47+
48+
| Command | Purpose |
49+
| --- | --- |
50+
| `npm start` | Start the local dev server and open the editor in a browser. |
51+
| `npm run build` | Compile TypeScript into `dist/`. |
52+
| `npm run check` | Run TypeScript type-checking without emitting files. |
53+
| `npm run prepare-pages` | Build the app and create a static `site/` artifact for publishing. |
54+
55+
## How It Works
56+
57+
### Editor architecture
58+
59+
- `src/initialize.ts` wires the shell, file operations, recent documents, and the split-view document container.
60+
- `src/setupBpmnDesignerServiceContainer.ts` configures the web-component-designer services, BPMN tools, extensions, and context menus.
61+
- `src/services/BpmnParserService.ts` converts between BPMN XML/BPMN DI and the custom BPMN web components used on the canvas.
62+
- `src/extensions/BpmnContextPadExtension.ts` provides single-selection overlay actions similar to the bpmn.io context pad.
63+
- `src/services/BpmnConnectionRouting.ts` keeps connected edges visually aligned while editing.
64+
- `src/widgets/` contains the BPMN element implementations and palette metadata.
65+
66+
### BPMN XML and DI handling
67+
68+
The editor persists both semantic BPMN model elements and diagram interchange information:
69+
70+
- BPMN model elements are written under `bpmn:process` and `bpmn:collaboration`.
71+
- BPMN DI shapes and edges are written under `bpmndi:BPMNDiagram` and `bpmndi:BPMNPlane`.
72+
- Color metadata is stored with the bpmn.io color namespace using `bioc:fill` and `bioc:stroke`.
73+
- Edge waypoints are regenerated when necessary so moved nodes keep coherent connections.
74+
75+
## GitHub Pages Deployment
76+
77+
The repository includes [deploy-pages.yml](.github/workflows/deploy-pages.yml), which publishes the editor to GitHub Pages on pushes to `main` or `master`, and also supports manual runs.
78+
79+
### Deployment flow
80+
81+
1. GitHub Actions installs dependencies with `npm ci`.
82+
2. `npm run prepare-pages` compiles the app and creates a `site/` folder.
83+
3. The staging script copies the required browser runtime packages into `site/vendor/` and rewrites the production `index.html` to use those vendored paths.
84+
4. The workflow uploads `site/` as the Pages artifact and deploys it.
85+
86+
### One-time repository setup
87+
88+
1. Open the repository settings on GitHub.
89+
2. Go to the Pages section.
90+
3. Set the build and deployment source to `GitHub Actions`.
91+
92+
After that, the site will be published at the standard Pages URL for the repository, typically `https://<owner>.github.io/<repo>/`.
93+
94+
### Local dry-run for deployment
95+
96+
If you want to inspect the production artifact before pushing:
97+
98+
```bash
99+
npm run prepare-pages
100+
npx web-dev-server --root-dir site --open
101+
```
102+
103+
The generated `site/` folder is ignored by Git and is safe to recreate at any time.
104+
105+
## Editing Workflow
106+
107+
Typical usage inside the editor:
108+
109+
1. Open an existing BPMN XML file or load the built-in sample.
110+
2. Add or connect elements from the palette and connection tools.
111+
3. Select an element to use the context pad for quick actions.
112+
4. Use the inspector to edit semantic fields and DI colors.
113+
5. Review or adjust the XML in the synchronized code view.
114+
6. Download the BPMN XML or save it under a new name.
115+
116+
## Current Scope and Limitations
117+
118+
- The editor focuses on diagram authoring and BPMN DI round-tripping, not process execution.
119+
- The supported BPMN surface is intentionally curated and does not cover every BPMN 2.0 element or attribute.
120+
- The replacement menu in the context pad is limited to compatible element families.
121+
- Advanced BPMN behaviors such as validation, simulation, token playback, and engine-specific extensions are out of scope.
122+
123+
## Repository Layout
124+
125+
```text
126+
.
127+
|-- index.html
128+
|-- src/
129+
| |-- extensions/
130+
| |-- services/
131+
| |-- toolbar/
132+
| `-- widgets/
133+
|-- scripts/
134+
| `-- prepare-pages.mjs
135+
|-- dist/
136+
`-- .github/workflows/
137+
```
138+
139+
## Notes
140+
141+
- The app currently uses import maps in development.
142+
- The GitHub Pages artifact avoids direct `node_modules` hosting by rewriting those imports to `site/vendor/` during staging.
143+
- The default sample is intentionally richer than a minimal three-node process so collaboration and artifact behavior can be exercised immediately.

0 commit comments

Comments
 (0)