Merge pull request #415 from com-pas/chore/sync-upstream-0.42.0

chore: sync upstream 0.42.0

Author: noraeb

.release-please-manifest.json

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

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.42.0](https://github.com/openscd/open-scd/compare/v0.41.0...v0.42.0) (2025-09-15)
+
+
+### Features
+
+* Add oscd api with plugin state ([#1696](https://github.com/openscd/open-scd/issues/1696)) ([1c457cf](https://github.com/openscd/open-scd/commit/1c457cf02a404a61b7ff09553223091bc5edd1f6))
+
+
+### Bug Fixes
+
+* Connected AP wizard element order ([#1703](https://github.com/openscd/open-scd/issues/1703)) ([cd3b39a](https://github.com/openscd/open-scd/commit/cd3b39ad45b6ddfc5d8c3641a5c120dd95bb5dd6))
+* **Import IED:** Fix order of edits ([#1698](https://github.com/openscd/open-scd/issues/1698)) ([0831fa4](https://github.com/openscd/open-scd/commit/0831fa4e4cde55a21c261b1b4b8b5994868509b0))
+* Settings addon translations ([cd3b39a](https://github.com/openscd/open-scd/commit/cd3b39ad45b6ddfc5d8c3641a5c120dd95bb5dd6))
+
 ## [0.41.0](https://github.com/openscd/open-scd/compare/v0.40.0...v0.41.0) (2025-08-04)
 
 

CONTRIBUTING.md

@@ -37,7 +37,7 @@ To develop, follow these steps :
 1. Install [↗ Node.js](https://nodejs.org/en/download/package-manager)
 
 > [!IMPORTANT]  
-> `Node.js` version should be set to `20.x.x` as there are incompatibilities with higher version
+> `Node.js` version should be set to `18.x.x` as there are incompatibilities with higher version
 
 2. Run `npm ci` in OpenSCD's root folder.
 
@@ -355,4 +355,4 @@ class MyClass {
   private foo = 1;
   private bar() {}
 }
-```
+```

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/compas-open-scd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compas-open-scd",
-  "version": "0.41.0-5",
+  "version": "0.42.0-1",
   "repository": "https://github.com/openscd/open-scd.git",
   "description": "OpenSCD CoMPAS Edition",
   "directory": "packages/compas-open-scd",

packages/compas-open-scd/src/open-scd.ts

@@ -34,6 +34,7 @@ import { ActionDetail } from '@material/mwc-list';
 
 import { officialPlugins as builtinPlugins } from '../public/js/plugins.js';
 import type { PluginSet, Plugin as CorePlugin } from '@openscd/core';
+import { OscdApi } from '@openscd/core';
 import { classMap } from 'lit-html/directives/class-map.js';
 import {
   newConfigurePluginEvent,
@@ -471,6 +472,7 @@ export class OpenSCD extends LitElement {
             .nsdoc=${this.nsdoc}
             .docs=${this.docs}
             .locale=${this.locale}
+            .oscdApi=${new OscdApi(tag)}
             .compasApi=${this.compasApi}
             class="${classMap({
               plugin: true,

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/addons/Settings.ts

@@ -7,7 +7,7 @@ import {
   LitElement,
   css,
 } from 'lit-element';
-import { get, registerTranslateConfig, Strings, use } from 'lit-translate';
+import { get, translate, registerTranslateConfig, Strings, use } from 'lit-translate';
 
 import '@material/mwc-button';
 import '@material/mwc-dialog';
@@ -204,7 +204,7 @@ export class OscdSettings extends LitElement {
         @change="${(evt: Event) => this.uploadNsdocFile(evt)}}"
       />
       <mwc-button
-        label="${get('settings.selectFileButton')}"
+        label="${translate('settings.selectFileButton')}"
         id="selectFileButton"
         @click=${() => {
           const input = <HTMLInputElement | null>(
@@ -360,39 +360,39 @@ export class OscdSettings extends LitElement {
   render(): TemplateResult {
     return html`<mwc-dialog
         id="settings"
-        heading="${get('settings.title')}"
+        heading="${translate('settings.title')}"
         @closing=${this.onClosing}
       >
         <form>
           <mwc-select
             fixedMenuPosition
             id="language"
             icon="language"
-            label="${get('settings.language')}"
+            label="${translate('settings.language')}"
           >
             ${Object.keys(this.languageConfig.languages).map(
               lang =>
                 html`<mwc-list-item
                   graphic="icon"
                   value="${lang}"
                   ?selected=${lang === this.settings.language}
-                  >${get(`settings.languages.${lang}`)}</mwc-list-item
+                  >${translate(`settings.languages.${lang}`)}</mwc-list-item
                 >`
             )}
           </mwc-select>
-          <mwc-formfield label="${get('settings.dark')}">
+          <mwc-formfield label="${translate('settings.dark')}">
             <mwc-switch
               id="dark"
               ?checked=${this.settings.theme === 'dark'}
             ></mwc-switch>
           </mwc-formfield>
-          <mwc-formfield label="${get('settings.mode')}">
+          <mwc-formfield label="${translate('settings.mode')}">
             <mwc-switch
               id="mode"
               ?checked=${this.settings.mode === 'pro'}
             ></mwc-switch>
           </mwc-formfield>
-          <mwc-formfield label="${get('settings.showieds')}">
+          <mwc-formfield label="${translate('settings.showieds')}">
             <mwc-switch
               id="showieds"
               ?checked=${this.settings.showieds === 'on'}
@@ -402,7 +402,7 @@ export class OscdSettings extends LitElement {
         <wizard-divider></wizard-divider>
         ${this.nsdUploadButton
           ? html`<section id="shownsdbutton">
-              <h3>${get('settings.loadNsdTranslations')}</h3>
+              <h3>${translate('settings.loadNsdTranslations')}</h3>
               ${this.renderFileSelect()}
             </section>`
           : html``}
@@ -413,22 +413,22 @@ export class OscdSettings extends LitElement {
           ${this.renderNsdocItem('IEC 61850-8-1')}
         </mwc-list>
         <mwc-button slot="secondaryAction" dialogAction="close">
-          ${get('cancel')}
+          ${translate('cancel')}
         </mwc-button>
         <mwc-button
           style="--mdc-theme-primary: var(--mdc-theme-error)"
           slot="secondaryAction"
           dialogAction="reset"
         >
-          ${get('reset')}
+          ${translate('reset')}
         </mwc-button>
         <mwc-button
           icon="save"
           trailingIcon
           slot="primaryAction"
           dialogAction="save"
         >
-          ${get('save')}
+          ${translate('save')}
         </mwc-button>
       </mwc-dialog>
       <slot></slot>