Merge pull request #350 from com-pas/chore/sync-with-open-scd-0.36.0

chore: Sync with open scd 0.36.0
chore: Update nginx image to 1.27.3

.release-please-manifest.json

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

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [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

@@ -38,3 +38,4 @@ How the documentation is organized.
 A high-level overview of how it’s organized will help you know where to look for certain things:
 
 - [⚖️ Decisions](docs/decisions/README.md) documents the decisions we made and why we made them.
+- [✏️ Edit event API](docs/core-api/edit-api.md) documents the edit event API.

docs/core-api/edit-api.md

@@ -0,0 +1,248 @@
+# Edit Event API
+
+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.
+
+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 newEditEvent<E extends Edit>(
+  edit: E,
+  initiator: Initiator = 'user'
+): EditEvent
+
+type Edit = Insert | Update | Remove | Edit[];
+
+type Initiator = 'user' | 'system' | 'undo' | 'redo' | string;
+
+```
+
+Example for remove.
+
+```ts
+import { newEditEvent, Remove } from '@openscd/core';
+
+const remove: Remove = { node: someNode };
+const removeEvent = newEditEvent(remove);
+
+someComponent.dispatchEvent(removeEvent);
+
+```
+
+
+### 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 Insert {
+  parent: Node;
+  node: Node;
+  reference: Node | null;
+}
+```
+
+
+### Remove
+
+This event will remove the node from the document.
+
+```ts
+interface Remove {
+  node: Node;
+}
+```
+
+
+### Update
+
+Update can add, remove or change attributes on an existing node. Existing attributes will only be removed, if `null` is passed as value in the event's `attributes` property.
+
+
+```ts
+interface Update {
+  element: Element;
+  attributes: Partial<Record<string, AttributeValue>>;
+}
+
+// Attirubte value
+
+type AttributeValue = string | null | NamespacedAttributeValue;
+
+type NamespacedAttributeValue = {
+  value: string | null;
+  namespaceURI: string | null;
+};
+```
+
+Example for adding and changing values.
+
+```ts
+
+const update: Update = {
+  element: elementToUpdate,
+  attributes: {
+    name: 'new name',
+    value: 'new value'
+  }
+};
+
+```
+
+To remove an existing value pass `null` as value.
+
+```ts
+
+const update: Update = {
+  element: elementToUpdate,
+  attributes: {
+    attributeToRemove: null
+  }
+};
+
+```
+
+Update also supports [Xml namespaces](https://developer.mozilla.org/en-US/docs/Related/IMSC/Namespaces#namespaced_attributes) for attributes. To change namespaced attributes you need to pass an `NamespacedAttributeValue` instead of a plain `string`.
+
+```ts
+
+const update: Update = {
+  element: elementToUpdate,
+  attributes: {
+    name: {
+      value: 'namespaced name',
+      namespaceURI: 'http://www.iec.ch/61850/2003/SCLcoordinates'
+    },
+    type: {
+      value: 'namespaced type',
+      namespaceURI: 'http://www.iec.ch/61850/2003/SCLcoordinates'
+    },
+  }
+};
+
+```
+
+Adding, updating and removing attributes with and without namespaces can be combined in a single `Update`.
+
+### 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 `newEditEvent` factory function.
+
+```ts
+import { newEditEvent } from '@openscd/core';
+
+const complexEditEvent = newEditEvent([ insert, update, remove ]);
+
+someComponent.dispatchEvent(complexEditEvent);
+
+```
+
+
+
+## History
+
+All edit events with initiator `user` will create a history log entry and can be undone and redone through the history addon.
+
+## Breaking changes due to migration
+Before the edit event API the editor action API was used to edit the `doc`. It is also custom event based and listens to the events of the type `editor-action`.
+For backwards compatibility the API is still supported, but it is recommended to use the edit event API instead. Internally editor actions are converted to edit events.
+With open SCD version **v0.36.0** and higher some editor action features are no longer supported see [Deprecated Editor Action API](#archives---editor-action-api-deprecated). 
+* The editor action properties `derived` and `checkValidity` do not have any effect.
+* All validation checks have been removed (i.e. check for unique `id` attribute on element before create).
+* The `title` for `ComplexAction` does not have any effect.
+
+---
+
+# Archives - Editor Action API (deprecated)
+
+### Event factory
+
+```ts
+
+function newActionEvent<T extends EditorAction>(
+  action: T,
+  initiator: Initiator = 'user',
+  eventInitDict?: CustomEventInit<Partial<EditorActionDetail<T>>>
+): EditorActionEvent<T>
+
+type SimpleAction = Update | Create | Replace | Delete | Move;
+type ComplexAction = {
+  actions: SimpleAction[];
+  title: string;
+  derived?: boolean;
+};
+type EditorAction = SimpleAction | ComplexAction;
+
+```
+
+
+### Create
+
+`Create` actions are converted to `Insert` events.
+
+```ts
+interface Create {
+  new: { parent: Node; element: Node; reference?: Node | null };
+  derived?: boolean;
+  checkValidity?: () => boolean;
+}
+```
+
+### Move
+
+`Move` actions are converted to `Insert` events.
+
+```ts
+interface Move {
+  old: { parent: Element; element: Element; reference?: Node | null };
+  new: { parent: Element; reference?: Node | null };
+  derived?: boolean;
+  checkValidity?: () => boolean;
+}
+```
+
+
+### Delete
+
+`Delete` actions are converted to `Remove` events.
+
+```ts
+interface Delete {
+  old: { parent: Node; element: Node; reference?: Node | null };
+  derived?: boolean;
+  checkValidity?: () => boolean;
+}
+```
+
+
+### Update
+
+`Update` actions are converted to `Update` events.
+
+```ts
+interface Update {
+  element: Element;
+  oldAttributes: Record<string, string | null>;
+  newAttributes: Record<string, string | null>;
+  derived?: boolean;
+  checkValidity?: () => boolean;
+}
+```
+
+### Replace
+
+`Replace` actions are converted to a complex event with `Remove` and `Insert` events.
+
+```ts
+interface Replace {
+  old: { element: Element };
+  new: { element: Element };
+  derived?: boolean;
+  checkValidity?: () => boolean;
+}
+```