Merge branch 'main' into feature/release_build_output

.env.example

@@ -0,0 +1 @@
+CHROME_PATH=

.github/workflows/save-pr-data-to-file.yml

@@ -18,7 +18,7 @@ jobs:
         run: echo ${{ github.event.pull_request.node_id }} > PR_NODE_ID.txt && echo ${{ github.event.action }} > EVENT_ACTION.txt
       - name: Archive PR node_id and event_action
         if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: PR_DATA
           path: |
@@ -29,7 +29,7 @@ jobs:
         run: echo ${{ github.event.pull_request.node_id }} > PR_NODE_ID.txt && echo ${{ github.event.review.state }} > REVIEW_STATE.txt
       - name: Archive PR and review_state
         if: github.event_name == 'pull_request_review'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: REVIEW_DATA
           path: |

.github/workflows/test-and-build.yml

@@ -3,7 +3,7 @@ on: pull_request
 
 jobs:
   test-and-build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/[email protected]

.github/workflows/test.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/[email protected]

.gitignore

@@ -25,3 +25,6 @@ node_modules/
 /lerna-debug.log
 
 .nx/cache
+
+# environment variables
+.env

.release-please-manifest.json

@@ -1,5 +1,5 @@
 {
-  "packages/openscd": "0.35.0",
-  "packages/core": "0.1.2",
-  ".": "0.35.0"
+  "packages/openscd": "0.37.0",
+  "packages/core": "0.1.4",
+  ".": "0.37.0"
 }

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.37.0](https://github.com/openscd/open-scd/compare/v0.36.0...v0.37.0) (2025-01-27)
+
+
+### Features
+
+* Edit api v3 ([#1615](https://github.com/openscd/open-scd/issues/1615)) ([ce39e2b](https://github.com/openscd/open-scd/commit/ce39e2b7bfcda40659f36e40659b1efd571f2a53))
+* **monorepo:** Add contributing guide ([#1588](https://github.com/openscd/open-scd/issues/1588)) ([dd692a8](https://github.com/openscd/open-scd/commit/dd692a8d9784aaf5f8509fdad5298293195d1465))
+
+## [0.36.0](https://github.com/openscd/open-scd/compare/v0.35.0...v0.36.0) (2024-11-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* Edit API v1 validation is no longer supported (e.g. edit api v1 checked if an elements id was unique in the document)
+* Edit event v1 properties `derived` and `checkValidity` will be ignored
+
+### Features
+
+* Allow .fsd file creation ([d9a4a0c](https://github.com/openscd/open-scd/commit/d9a4a0c6f6a0c9c86927d80bf5c81b4e9f6fc6d5))
+* Edit events v1 will be converted event v2 ([14e933e](https://github.com/openscd/open-scd/commit/14e933ed776ec5592c3c38e84b9884fa41a05e81))
+* Editor plugins can be rendered without an active document ([8b06a37](https://github.com/openscd/open-scd/commit/8b06a375ecfbc6275c5238d4a95383f4e80449b8))
+* Handle Config Plugin Events ([a510664](https://github.com/openscd/open-scd/commit/a5106648367dad831a248b734cd5c34aa1043d89))
+* render plugin download UI on event ([44a51f0](https://github.com/openscd/open-scd/commit/44a51f05797e8dd6345215c177a2e7b68e189d69))
+* Support edit api v2 ([#1581](https://github.com/openscd/open-scd/issues/1581)) ([14e933e](https://github.com/openscd/open-scd/commit/14e933ed776ec5592c3c38e84b9884fa41a05e81))
+
+
+### Bug Fixes
+
+* 1553 LN LN0 wizards read only attributes ([#1568](https://github.com/openscd/open-scd/issues/1568)) ([87aa759](https://github.com/openscd/open-scd/commit/87aa75961c7ef0bfe11810d2fa5d4e08704da033)), closes [#1553](https://github.com/openscd/open-scd/issues/1553)
+* correct plug-ins' paths ([a7a14ce](https://github.com/openscd/open-scd/commit/a7a14ced59294d8a24daabf5ecdc76a5dbb75237))
+
 ## [0.35.0](https://github.com/openscd/open-scd/compare/v0.34.0...v0.35.0) (2024-07-17)
 
 ### Features

README.md

@@ -7,13 +7,13 @@
 
 Open Substation Communication Designer is an editor for SCL files as described in `IEC 61850-6`.
 
-> Try it out at [openscd.github.io](https://openscd.github.io)!
+> Try it out at [↗ openscd.github.io](https://openscd.github.io)!
 
 Make sure your web browser has enough free memory! If needed, disable plug-ins and close unused browser tabs.
 
 ## Installation
 
-In order to install OpenSCD on your local device (only for you), simply visit [openscd.github.io](https://openscd.github.io), click the "Install OpenSCD" button in your address bar (Chrome or Edge on desktop) or click the "Add OpenSCD to home screen" notification in any mobile browser.
+In order to install OpenSCD on your local device (only for you), simply visit [↗ openscd.github.io](https://openscd.github.io), click the "Install OpenSCD" button in your address bar (Chrome or Edge on desktop) or click the "Add OpenSCD to home screen" notification in any mobile browser.
 
 In order to install your own instance of OpenSCD on your own webserver (e.g. on your company intranet), simply download [our latest release](https://github.com/openscd/open-scd/releases/latest) (`open-scd.zip` or `open-scd.tar.gz`) and extract the archive contents into the "webroot" directory of your web server.
 
@@ -24,17 +24,9 @@ If you don't have your own webserver but still want your own version of OpenSCD
 We gather the available plug-ins from the community in the [plug-ins](docs/plug-ins.md) file.  
 If you would like to list your plug-in here, please open a pull request.
 
-## Development
-
-This repository is a [↗ monorepo](https://en.wikipedia.org/wiki/Monorepo), made up of several packages.
-To find out more about the development of each packages, such as the base distribution or the plugins, please refer to their respective READMEs:
-- [open-scd](packages/openscd/README.md): provides the base distribution available on [openscd.github.io](https://openscd.github.io)
-- [core](packages/core/README.md): provides the agreed api of OpenSCD Core
-
 ## Contributing
 
-The easiest way to get in touch is to join us on the [Zulip Chat](https://openscd.zulipchat.com/join/k3cyur3wx526tvafkjwubhjn/). 
-If you say "hi" there we will be more than happy to help you find your way around this project.
+See [Contributing Guide](CONTRIBUTING.md)
 
 ## Documentation
 

docs/core-api/edit-api.md

@@ -1,13 +1,123 @@
-# Edit Event API
+# Edit Event API v2
 
-Open SCD offers an API for editing the scd document which can be used with [Html Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent). The main Open SCD components listens to events of the type `oscd-edit`, applies the changes to the `doc` and updates the `editCount` property.
+Open SCD offers an API for editing the scd document which can be used with [Html Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent). The main Open SCD components listens to events of the type `oscd-edit-v2`, applies the changes to the `doc` and updates the `editCount` property.
 
 The edits to the `doc` will be done in place, e.g. the `doc` changes but will keep the same reference. If your plugin needs to react to changes in the doc, you should listen to changes in the `editCount` property.
 
 ## Event factory
 
 Open SCD core exports a factory function for edit events, so you do not have to build them manually.
 
+```ts
+function newEditEventV2<E extends EditV2>(
+  edit: E,
+  options?: EditEventOptionsV2
+): EditEventV2
+
+type EditV2 = InsertV2 | SetAttributesV2 | SetTextContentV2 | RemoveV2 | EditV2[];
+
+interface EditEventOptionsV2 = {
+  title?: string;
+  squash?: boolean;
+  createHistoryEntry?: boolean;
+};
+```
+
+### EditEventOptionsV2
+
+* `title` set a title to be shown in the history.
+* `squash` squash edit with previous history entry, this is useful if you want to create multiple edits based on an user action, but need the updated `doc` before applying each edit. Defaults to `false`.
+* `createHistoryEntry` decides whether a history for the `edit` should be created. Defaults to `true`.
+
+### Insert
+
+Insert events can be used to add new nodes or move existing nodes in the document. Since a node can only have one parent, using an insert on an existing node will replace it's previous parent with the new parent, essentially moving the node to a different position in the xml tree.
+
+If the reference is not `null`, the node will be inserted before the reference node. The reference has to be a child node of the parent. And if the reference is `null` the node will be added as the last child of the parent.
+
+```ts
+interface InsertV2 {
+  parent: Node;
+  node: Node;
+  reference: Node | null;
+}
+```
+
+### Remove
+
+This event will remove the node from the document.
+
+```ts
+interface RemoveV2 {
+  node: Node;
+}
+```
+
+### SetAttributes
+
+Sets attributes for the element, can set both regular and namespaced attributes.
+
+```ts
+interface SetAttributesV2 {
+  element: Element;
+  attributes: Partial<Record<string, string | null>>;
+  attributesNS: Partial<Record<string, Partial<Record<string, string | null>>>>;
+}
+```
+
+To set a namespaced attribute see the following example. Here we are setting the attribute `exa:type` for the namespace `https://example.com` to `secondary`.
+
+```ts
+const setNamespacedAttributes: SetAttributesV2 = {
+  element,
+  attributes: {},
+  attributesNS: {
+    "https://example.com": {
+      "exa:type": "secondary"
+    }
+  }
+}
+```
+
+### SetTextContent
+
+Sets the text content of the element, removes any other children. To remove text content you can pass `null` as value for `textContent`.
+
+```ts
+interface SetTextContentV2 {
+  element: Element;
+  textContent: string;
+}
+```
+
+### Complex edits
+
+Complex edits can be used to apply multiple edits as a single event. This will create a single entry in the history. You can create complex edit events by passing an array of edit events to the `newEditEventV2` factory function.
+
+```ts
+import { newEditEventV2 } from '@openscd/core';
+
+const complexEditEvent = newEditEventV2([ insert, update, remove ]);
+
+someComponent.dispatchEvent(complexEditEvent);
+
+```
+
+## History
+
+All edit events with the option `createHistoryEntry` will create a history log entry and can be undone and redone through the history addon.
+
+
+# Archives
+
+## Edit Event API v1 (deprecated)
+
+The edit event API v1 is still available and listens to events of the type `oscd-edit`.
+
+## Event factory
+
+Open SCD core exports a factory function for edit events, so you do not have to build them manually.
+
 ```ts
 function newEditEvent<E extends Edit>(
   edit: E,
@@ -158,7 +268,7 @@ With open SCD version **v0.36.0** and higher some editor action features are no
 
 ---
 
-# Archives - Editor Action API (deprecated)
+## Editor Action API (deprecated)
 
 ### Event factory
 

docs/decisions/0003-extract-plugins.md

@@ -0,0 +1,36 @@
+# ADR-0003 - Externalize OpenSCD core plugins
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+For a better expandability we would like to extract all plugins in a new plugins repository.
+
+## Decision
+
+Following the architectural decision in [OpenSCD Theming](./../0001-ADR-Theming.md) we will extract all OpenSCD Core plugins to an external repository.
+Doing so OpenSCD Core will be streamlined and a clean interface and structure for plugins will be provided for custom extensions.
+Before extracting this plugins a shared UI-Components module will be extracted. This UI-Components provide reusable UI-Components based on [NX](https://nx.dev/) for faster development for OpenSCD Core and custom plugins. This new repository will be created as mono repository to facility the plugins development and simplify the release and deployment process.
+
+Plugins will be moved to repository [OpenSCD official Plugins](https://github.com/openscd/oscd-official-plugins) and the release strategy is defined [here](./0004-openscd-release-and-deploy-strategy.md).
+As final task the current documentation will be added with a new section `How to add new and custom OpenSCD plugins` to support developers to follow the concept.
+
+## Consequences
+
+- Clean Code in OpenSCD Core
+- Clear architectural structure of plugins
+
+- Building OpenSCD is more then building a simple repository
+- Clear path must be defined how to extend OpenSCD with custom plugins (full software cycle till deployment)
+- Release process for OpenSCD Core and OpenSCD official plugins
+
+## Agreed procedure
+
+- move the plugins without any components abstraction to the external plugins repository
+  - copy all required dependencies regardless of code duplication
+- integrate the plugins as submodules within OpenSCD core in the pipeline
+- later on we can extract step by step for each plugin UI-Components

docs/decisions/0004-openscd-release-and-deployment-strategy.md

@@ -0,0 +1,32 @@
+# ADR-0004 - Technical solution for releasing and deployments
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+Based on the [decision](./0003-extract-plugins.md) to externalize plugins in proper plugins repository a new release and deployment strategy needs to be defined.
+This plugins repository is solved as mono repository.
+
+## Decision
+
+### Release process 
+
+Since OpenSCD is based on [NX](https://nx.dev/) the release strategy needs to rely on NX as well and must allow single releases of sub modules within this mono repository.
+Such feature is provided by [NX release](https://nx.dev/recipes/nx-release) specially when using the [NX independently release feature](https://nx.dev/recipes/nx-release/release-projects-independently).
+
+A possible release command would look like:
+```
+  nx release --projects=plugin-1,plugin-3
+```
+
+## Consequences
+
+- Process needs to be documented so that all developers can easily follow it
+- The building of complete OpenSCD Editor, OpenSCD Core + OpenSCD plugins, depends now on two repositories
+- Custom OpenSCD eg. CoMPAS OpenSCD will be cleaner and more code can be reused
+- Similar Look & Feel of plugins if shared UI-Components are used
+- Faster plugin development and integration into OpenSCD Core