Merge remote-tracking branch 'origin/main' into feat/programatic-plug…

…in-activation

.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.36.0",
-  "packages/core": "0.1.3",
-  ".": "0.36.0"
+  "packages/openscd": "0.37.0",
+  "packages/core": "0.1.4",
+  ".": "0.37.0"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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)
 
 

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
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openscd-monorepo",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "OpenSCD base distribution and plugins",
   "private": true,
   "workspaces": [

packages/core/foundation.ts

@@ -13,7 +13,7 @@ export {
   isNamespaced,
   isUpdate,
   isRemove,
-} from './foundation/edit-event.js';
+} from './foundation/deprecated/edit-event.js';
 export type {
   EditEvent,
   Edit,
@@ -22,7 +22,31 @@ export type {
   NamespacedAttributeValue,
   Update,
   Remove,
+} from './foundation/deprecated/edit-event.js';
+
+export type {
+  EditV2,
+  InsertV2,
+  RemoveV2,
+  SetTextContentV2,
+  SetAttributesV2,
+} from './foundation/edit.js';
+export {
+  isEditV2,
+  isRemoveV2,
+  isInsertV2,
+  isComplexV2,
+  isSetAttributesV2,
+  isSetTextContentV2
+} from './foundation/edit.js';
+export type {
+  EditEventV2,
+  EditEventOptionsV2,
+  EditDetailV2
 } from './foundation/edit-event.js';
+export { newEditEventV2 } from './foundation/edit-event.js';
+
+export { handleEditV2 } from './foundation/handle-edit.js';
 
 export { cyrb64 } from './foundation/cyrb64.js';