doc: Add edit API v3 doc

docs/core-api/edit-api.md

@@ -1,13 +1,110 @@
-# 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;
+}
+```
+
+## 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 +255,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