Merge branch 'openscd:main' into main

docs/decisions/0003-extract-plugins.md

@@ -0,0 +1,36 @@
+# ADR-0003 - Externalize OpenSCD core plugins
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+For a better expandability we would like to extract all plugins in a new plugins repository.
+
+## Decision
+
+Following the architectural decision in [OpenSCD Theming](./../0001-ADR-Theming.md) we will extract all OpenSCD Core plugins to an external repository.
+Doing so OpenSCD Core will be streamlined and a clean interface and structure for plugins will be provided for custom extensions.
+Before extracting this plugins a shared UI-Components module will be extracted. This UI-Components provide reusable UI-Components based on [NX](https://nx.dev/) for faster development for OpenSCD Core and custom plugins. This new repository will be created as mono repository to facility the plugins development and simplify the release and deployment process.
+
+Plugins will be moved to repository [OpenSCD official Plugins](https://github.com/openscd/oscd-official-plugins) and the release strategy is defined [here](./0004-openscd-release-and-deploy-strategy.md).
+As final task the current documentation will be added with a new section `How to add new and custom OpenSCD plugins` to support developers to follow the concept.
+
+## Consequences
+
+- Clean Code in OpenSCD Core
+- Clear architectural structure of plugins
+
+- Building OpenSCD is more then building a simple repository
+- Clear path must be defined how to extend OpenSCD with custom plugins (full software cycle till deployment)
+- Release process for OpenSCD Core and OpenSCD official plugins
+
+## Agreed procedure
+
+- move the plugins without any components abstraction to the external plugins repository
+  - copy all required dependencies regardless of code duplication
+- integrate the plugins as submodules within OpenSCD core in the pipeline
+- later on we can extract step by step for each plugin UI-Components

docs/decisions/0004-openscd-release-and-deployment-strategy.md

@@ -0,0 +1,32 @@
+# ADR-0004 - Technical solution for releasing and deployments
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+Based on the [decision](./0003-extract-plugins.md) to externalize plugins in proper plugins repository a new release and deployment strategy needs to be defined.
+This plugins repository is solved as mono repository.
+
+## Decision
+
+### Release process 
+
+Since OpenSCD is based on [NX](https://nx.dev/) the release strategy needs to rely on NX as well and must allow single releases of sub modules within this mono repository.
+Such feature is provided by [NX release](https://nx.dev/recipes/nx-release) specially when using the [NX independently release feature](https://nx.dev/recipes/nx-release/release-projects-independently).
+
+A possible release command would look like:
+```
+  nx release --projects=plugin-1,plugin-3
+```
+
+## Consequences
+
+- Process needs to be documented so that all developers can easily follow it
+- The building of complete OpenSCD Editor, OpenSCD Core + OpenSCD plugins, depends now on two repositories
+- Custom OpenSCD eg. CoMPAS OpenSCD will be cleaner and more code can be reused
+- Similar Look & Feel of plugins if shared UI-Components are used
+- Faster plugin development and integration into OpenSCD Core

packages/openscd/package.json

@@ -172,4 +172,4 @@
     ],
     "commitUrlFormat": "https://github.com/openscd/open-scd/commits/{{hash}}"
   }
-}
+}

packages/openscd/src/open-scd.ts

@@ -254,7 +254,7 @@ export class OpenSCD extends LitElement {
 
   private resetPlugins(): void {
     this.storePlugins(
-      (builtinPlugins as Plugin[]).concat(this.parsedPlugins).map(plugin => {
+      (this.getBuiltInPlugins() as Plugin[]).concat(this.parsedPlugins).map(plugin => {
         return {
           ...plugin,
           installed: plugin.default ?? false,
@@ -316,7 +316,7 @@ export class OpenSCD extends LitElement {
       const isBuiltIn = !plugin?.official
       if (!isBuiltIn){ return plugin };
 
-      const builtInPlugin = [...builtinPlugins, ...this.parsedPlugins]
+      const builtInPlugin = [...this.getBuiltInPlugins(), ...this.parsedPlugins]
         .find(p => p.src === plugin.src);
 
         return <Plugin>{
@@ -367,14 +367,14 @@ export class OpenSCD extends LitElement {
     const localPluginConfigs = this.getPluginConfigsFromLocalStorage()
 
     const overwritesOfBultInPlugins = localPluginConfigs.filter((p) => {
-      return builtinPlugins.some(b => b.src === p.src)
+      return this.getBuiltInPlugins().some(b => b.src === p.src)
     })
 
     const userInstalledPlugins = localPluginConfigs.filter((p) => {
-      return !builtinPlugins.some(b => b.src === p.src)
+      return !this.getBuiltInPlugins().some(b => b.src === p.src)
     })
 
-    const mergedBuiltInPlugins = builtinPlugins.map((builtInPlugin) => {
+    const mergedBuiltInPlugins = this.getBuiltInPlugins().map((builtInPlugin) => {
       const noopOverwrite = {}
       const overwrite = overwritesOfBultInPlugins
         .find(p => p.src === builtInPlugin.src)
@@ -404,6 +404,10 @@ export class OpenSCD extends LitElement {
     this.storePlugins(newPlugins);
   }
 
+  protected getBuiltInPlugins(): CorePlugin[] {
+    return builtinPlugins as CorePlugin[]
+  }
+
   private addContent(plugin: Omit<Plugin, 'content'>): Plugin {
     const tag = this.pluginTag(plugin.src);
 

packages/openscd/src/plugins.ts

@@ -1,4 +1,4 @@
-function generatePluginPath(plugin: string): string {
+export function generatePluginPath(plugin: string): string {
   return location.origin+location.pathname+plugin;
 }
 

packages/openscd/test/mock-open-scd.ts

@@ -4,16 +4,23 @@ import {
   html,
   queryAssignedNodes,
   query,
+  property
 } from 'lit-element';
 import { OscdWizards } from '../src/addons/Wizards.js';
 import { WizardFactory } from '../src/foundation.js';
 import { OpenSCD } from '../src/open-scd.js';
 import { WizardDialog } from '../src/wizard-dialog.js';
 import { OscdHistory } from '../src/addons/History.js';
 import { OscdLayout } from '../src/addons/Layout.js';
+// import type { Plugin } from '@openscd/core';
+import { Plugin } from '../src/plugin';
 
 @customElement('mock-open-scd')
 export class MockOpenSCD extends OpenSCD {
+
+  @property({ attribute: false })
+  mockPlugins: Plugin[] = []
+
   @queryAssignedNodes()
   _plugins!: Array<HTMLElement>;
 
@@ -32,10 +39,17 @@ export class MockOpenSCD extends OpenSCD {
 
   render(): TemplateResult {
     return html`
-    ${this.renderHosting()}
-    ${super.render()}`;
+      ${this.renderHosting()}
+      ${super.render()}
+    `;
+  }
+
+  protected getBuiltInPlugins(): Plugin[]{
+    return this.mockPlugins;
   }
 
+
+
   getPlugin<T extends HTMLElement>(name: string): T | undefined {
     return this._plugins.find(
       p => p.tagName.toLowerCase() === name.toLowerCase()