feat: Add oscd api with plugin state (openscd#1696)

Author: clepski

docs/core-api/oscd-api.md

@@ -0,0 +1,40 @@
+# OSCD API
+
+Open scd passes an API object as the property `oscdApi` to every plugin. At the moment the API only includes the plugin state API. Here is an example usage in a Lit based plugin.
+
+```
+import { OscdApi } from '@openscd/core';
+
+class SomePlugin extends LitElement {
+
+  @property()
+  oscdApi: OscdApi | null = null;
+
+  connectedCallback() {
+    const pluginState = this.oscdApi?.pluginState.getState();
+
+    ...
+  }
+
+  disconnectedCallback() {
+    this.oscdApi?.pluginState.setState(someStateObject);
+  }
+}
+```
+
+⚠️ Be aware that not every open scd distribution provides this API, so your plugin should have a null check if you want it to be compatible with other distributions.
+
+## Plugin state API
+
+The plugin state API stores an arbitrary object as your plugin's state in memory. Be aware that this state is only persisted during the open scd distribution's runtime and will not be stored in local storage for example.
+
+```
+interface PluginStateApi {
+  setState(state: PluginState | null): void;
+
+  getState(): PluginState | null;
+
+  updateState(partialState: Partial<PluginState>): void
+}
+```
+

packages/core/api/api.ts

@@ -0,0 +1,9 @@
+import { PluginStateApi } from './plugin-state-api.js';
+
+export class OscdApi {
+  public pluginState: PluginStateApi;
+
+  constructor(pluginTag: string) {
+    this.pluginState = new PluginStateApi(pluginTag);
+  }
+}

packages/core/api/plugin-state-api.ts

@@ -0,0 +1,37 @@
+type PluginState = {
+  [key: string]: unknown
+}
+
+export class PluginStateApi {
+  private static state: { [tag: string]: PluginState | null } = {};
+  private pluginTag: string;
+
+  constructor(tag: string) {
+    this.pluginTag = tag;
+  }
+
+  public setState(state: PluginState | null): void {
+    this.setPluginState(state);
+  }
+
+  public getState(): PluginState | null {
+    return this.getPluginState();
+  }
+
+  public updateState(partialState: Partial<PluginState>): void {
+    const pluginState = this.getPluginState();
+    const patchedState = {
+      ...pluginState,
+      ...partialState
+    };
+    this.setPluginState(patchedState);
+  }
+
+  private setPluginState(state: PluginState | null): void {
+    PluginStateApi.state[this.pluginTag] = state;
+  }
+
+  private getPluginState(): PluginState | null {
+    return PluginStateApi.state[this.pluginTag] ?? null;
+  }
+}

packages/core/foundation.ts

@@ -66,3 +66,5 @@ export function crossProduct<T>(...arrays: T[][]): T[][] {
     [[]]
   );
 }
+
+export { OscdApi } from './api/api.js';

packages/openscd/src/open-scd.ts

@@ -45,6 +45,7 @@ import type {
   Plugin as CorePlugin,
   EditCompletedEvent,
 } from '@openscd/core';
+import { OscdApi } from '@openscd/core';
 
 import { HistoryState, historyStateEvent } from './addons/History.js';
 
@@ -431,6 +432,7 @@ export class OpenSCD extends LitElement {
             .nsdoc=${this.nsdoc}
             .docs=${this.docs}
             .locale=${this.locale}
+            .oscdApi=${new OscdApi(tag)}
             class="${classMap({
               plugin: true,
               menu: plugin.kind === 'menu',

packages/plugins/src/editors/IED.ts

@@ -26,26 +26,30 @@ import {
 } from '@openscd/open-scd/src/foundation.js';
 import { Nsdoc } from '@openscd/open-scd/src/foundation/nsdoc.js';
 import { getIcon } from '@openscd/open-scd/src/icons/icons.js';
+import { OscdApi } from '@openscd/core';
 
 /** An editor [[`plugin`]] for editing the `IED` section. */
 export default class IedPlugin extends LitElement {
   /** The document being edited as provided to plugins by [[`OpenSCD`]]. */
   @property()
   doc!: XMLDocument;
-
+  
   @property({ type: Number })
   editCount = -1;
-
+  
   /** All the nsdoc files that are being uploaded via the settings. */
   @property()
   nsdoc!: Nsdoc;
-
+  
+  @property()
+  oscdApi: OscdApi | null = null;
+  
   @state()
   selectedIEDs: string[] = [];
-
+  
   @state()
   selectedLNClasses: string[] = [];
-
+  
   @state()
   private get iedList(): Element[] {
     return this.doc
@@ -61,26 +65,26 @@ export default class IedPlugin extends LitElement {
     const uniqueLNClassList: string[] = [];
     if (currentIed) {
       return Array.from(currentIed.querySelectorAll('LN0, LN'))
-        .filter(element => element.hasAttribute('lnClass'))
-        .filter(element => {
-          const lnClass = element.getAttribute('lnClass') ?? '';
-          if (uniqueLNClassList.includes(lnClass)) {
-            return false;
-          }
-          uniqueLNClassList.push(lnClass);
-          return true;
-        })
-        .sort((a, b) => {
-          const aLnClass = a.getAttribute('lnClass') ?? '';
-          const bLnClass = b.getAttribute('lnClass') ?? '';
-
-          return aLnClass.localeCompare(bLnClass);
-        })
-        .map(element => {
-          const lnClass = element.getAttribute('lnClass');
-          const label = this.nsdoc.getDataDescription(element).label;
-          return [lnClass, label];
-        }) as string[][];
+      .filter(element => element.hasAttribute('lnClass'))
+      .filter(element => {
+        const lnClass = element.getAttribute('lnClass') ?? '';
+        if (uniqueLNClassList.includes(lnClass)) {
+          return false;
+        }
+        uniqueLNClassList.push(lnClass);
+        return true;
+      })
+      .sort((a, b) => {
+        const aLnClass = a.getAttribute('lnClass') ?? '';
+        const bLnClass = b.getAttribute('lnClass') ?? '';
+        
+        return aLnClass.localeCompare(bLnClass);
+      })
+      .map(element => {
+        const lnClass = element.getAttribute('lnClass');
+        const label = this.nsdoc.getDataDescription(element).label;
+        return [lnClass, label];
+      }) as string[][];
     }
     return [];
   }
@@ -101,6 +105,16 @@ export default class IedPlugin extends LitElement {
 
   lNClassListOpenedOnce = false;
 
+  connectedCallback(): void {
+    super.connectedCallback();
+    this.loadPluginState();
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.storePluginState();
+  }
+
   protected updated(_changedProperties: PropertyValues): void {
     super.updated(_changedProperties);
 
@@ -132,6 +146,23 @@ export default class IedPlugin extends LitElement {
     }
   }
 
+  private loadPluginState(): void {
+    const stateApi = this.oscdApi?.pluginState;
+    const selectedIEDs: string[] | null = (stateApi?.getState()?.selectedIEDs as string[]) ?? null;
+    
+    if (selectedIEDs) {
+      this.onSelectionChange(selectedIEDs);
+    }
+  }
+
+  private storePluginState(): void {
+    const stateApi = this.oscdApi?.pluginState;
+    
+    if (stateApi) {
+      stateApi.setState({ selectedIEDs: this.selectedIEDs });
+    }
+  }
+
   private calcSelectedLNClasses(): string[] {
     const somethingSelected = this.selectedLNClasses.length > 0;
     const lnClasses = this.lnClassList.map(lnClassInfo => lnClassInfo[0]);
@@ -147,6 +178,29 @@ export default class IedPlugin extends LitElement {
     return selectedLNClasses;
   }
 
+  private onSelectionChange(selectedIeds: string[]): void {
+    const equalArrays = <T>(first: T[], second: T[]): boolean => {
+      return (
+        first.length === second.length &&
+        first.every((val, index) => val === second[index])
+      );
+    };
+    
+    const selectionChanged = !equalArrays(
+      this.selectedIEDs,
+      selectedIeds
+    );
+    
+    if (!selectionChanged) {
+      return;
+    }
+    
+    this.lNClassListOpenedOnce = false;
+    this.selectedIEDs = selectedIeds;
+    this.selectedLNClasses = [];
+    this.requestUpdate('selectedIed');
+  }
+
   render(): TemplateResult {
     const iedList = this.iedList;
     if (iedList.length > 0) {
@@ -158,28 +212,7 @@ export default class IedPlugin extends LitElement {
             id="iedFilter"
             icon="developer_board"
             .header=${get('iededitor.iedSelector')}
-            @selected-items-changed="${(e: SelectedItemsChangedEvent) => {
-              const equalArrays = <T>(first: T[], second: T[]): boolean => {
-                return (
-                  first.length === second.length &&
-                  first.every((val, index) => val === second[index])
-                );
-              };
-
-              const selectionChanged = !equalArrays(
-                this.selectedIEDs,
-                e.detail.selectedItems
-              );
-
-              if (!selectionChanged) {
-                return;
-              }
-
-              this.lNClassListOpenedOnce = false;
-              this.selectedIEDs = e.detail.selectedItems;
-              this.selectedLNClasses = [];
-              this.requestUpdate('selectedIed');
-            }}"
+            @selected-items-changed="${(e: SelectedItemsChangedEvent) => this.onSelectionChange(e.detail.selectedItems)}"
           >
             ${iedList.map(ied => {
               const name = getNameAttribute(ied);

packages/plugins/test/integration/editors/IED.test.ts

@@ -17,6 +17,8 @@ import { LNContainer } from '../../../src/editors/ied/ln-container.js';
 import { DOContainer } from '../../../src/editors/ied/do-container.js';
 import { DAContainer } from '../../../src/editors/ied/da-container.js';
 import { MockOpenSCD } from '@openscd/open-scd/test/mock-open-scd.js';
+import { OscdApi } from '@openscd/core';
+import { PluginStateApi } from '../../../../core/dist/api/plugin-state-api.js';
 
 describe('IED Plugin', () => {
   if (customElements.get('ied-plugin') === undefined)
@@ -42,6 +44,7 @@ describe('IED Plugin', () => {
 
   describe('with a doc loaded', () => {
     let doc: XMLDocument;
+    let oscdApi: OscdApi;
 
     describe('containing no IEDs', () => {
       beforeEach(async () => {
@@ -106,9 +109,11 @@ describe('IED Plugin', () => {
           .then(response => response.text())
           .then(str => new DOMParser().parseFromString(str, 'application/xml'));
         nsdoc = await initializeNsdoc();
+        oscdApi = new OscdApi('IED');
+        oscdApi.pluginState.setState(null);
         parent = await fixture(
           html`<mock-open-scd
-            ><ied-plugin .doc="${doc}" .nsdoc="${nsdoc}"></ied-plugin
+            ><ied-plugin .doc="${doc}" .nsdoc="${nsdoc}" .oscdApi=${oscdApi}></ied-plugin
           ></mock-open-scd>`
         );
         element = parent.getActivePlugin();
@@ -370,6 +375,28 @@ describe('IED Plugin', () => {
         primaryButton.click();
         await element.updateComplete;
       }
+
+      describe('load and store selected IEDs', () => {
+        it('should store selected IEDs on disconnected', async () => {
+          await selectIed('IED3');
+          element.disconnectedCallback();
+
+          const api = new OscdApi('IED');
+          expect(api.pluginState.getState()).to.deep.equal({ selectedIEDs: ['IED3'] });
+        });
+      });
+
+      describe('with stored plugin state', () => {
+        beforeEach(() => {
+          oscdApi.pluginState.setState({ selectedIEDs: ['IED3'] });
+        });
+
+        it('should load previously saved IED', () => {
+          element.connectedCallback();
+
+          expect(element.selectedIEDs).to.deep.equal(['IED3']);
+        });
+      });
     });
   });