openscd / open-scd-core Goto Github PK

XML editing action for removing a node from a given document

As a PO
I would like to know what needs to done in OpenSCD-core migration
So I can prioritize/plan activities and reduce frustration

Background;
During the CoMPAS open migration, @juancho0202 and others noticed that basic stuff is needed to move on.

Acceptance criteria:
Open list/project with all related (on Github)
Diagram with dependencies (if needed)

Todo: make a list of foundation issues that needs to be fixed

On incoming EditorActionEvent<Insert> {detail: { parent, node, reference }}, will call parent.insertBefore(node, reference). This can be used to create or move XML elements in the editor.

As a OpenSCD user
I want to see the code quality of OpenSCD
So I have confidence in the software and maintainability

Example:
SonarQube could work here.

As a plugin author, I want to trigger the LitElement lifecycle after a successful edit-event.

Requirements

• push property down to editor and menu plugins called editCount that is changed on each edit-event but also on each undo and redo.

• github action to publish open scd core on npm
• @openscd/create-plugin: init CLI for external plugin authors
• Use release please

We propose to add the ability to load multiple plugins from "remote plugin registries" (i.e. plugins.json files hosted elsewhere) and consequently to group plugins into plugin sets in the user interface, which also share common settings (see #26). The UI terms for these concepts could be "extension" and "extension set", respectively.

The default plugin set in the default distribution will be installed under the name "OpenSCD". An example installation of a user who uses some default OpenSCD plugins and two different instances of the CoMPAS plugin set (e.g. one locally hosted with a postgres db and another hosted at compas.example.com with a BaseX db) could be loaded from this file:

{
  "OpenSCD": "/plugins.json",
  "CoMPAS Postgres": "/compas-plugins.json",
  "CoMPAS BaseX": "https://compas.example.com/compas-plugins.json"
}

and look like this at runtime:

{
  "OpenSCD": [
      {
	name: 'Substation',
	src: '/editors/Substation.js',
	icon: 'margin',
	default: true,
	kind: 'editor',
      },
      {
	name: 'IED',
	src: '/editors/IED.js',
	icon: 'developer_board',
	default: false,
	kind: 'editor',
      },
      ...etc
  ],
  "CoMPAS Postgres": [
       {
	name: 'CoMPAS Versions',
	src: '/editors/CompasVersions.js',
	icon: 'copy_all',
	default: true,
	kind: 'editor',
      },
      {
	name: 'Open project',
	src: '/menu/CompasOpen.js',
	icon: 'folder_open',
	default: true,
	kind: 'menu',
	requireDoc: false,
	position: 'top'
      },
      ...etc
  ],
  "CoMPAS BaseX": [
       {
	name: 'CoMPAS Versions',
	src: 'https://compas.example.com/editors/CompasVersions.js',
	icon: 'copy_all',
	default: true,
	kind: 'editor',
      },
      {
	name: 'Open project',
	src: 'https://compas.example.com/menu/CompasOpen.js',
	icon: 'folder_open',
	default: true,
	kind: 'menu',
	requireDoc: false,
	position: 'top'
      },
      ...etc
  ]
}

In this case the two different sets of CoMPAS plugins would have two sets of settings which the plugins within each set share internally.

NB: Since a plugin is uniquely identified by its URL, this would mean that a single instance of a plugin can only be active in one plugin set at a time. If the user wants that plugin to share its settings with another plugin set instead, they will have to deactivate the plugin in the first set and activate it in the second set afterwards.

Currently in an open-scd-core plugin, as far as I can tell undo/redo buttons do not request an update on the currently in use plugin. Or -- perhaps the editCount is not being correctly modified.

The undo/redo action is happening correctly but the visual display does not appear to be updated.

I have ensured that my plugin has properties on it which should effect a change, so the plugin begins:

@property({ attribute: false })
doc!: XMLDocument;

@property() docName!: string;

@property() editCount!: number;

It looks as though editCount is undefined:

Even though edits have been made:

Happy to provide additional information.

After introducing translations to our dynamic setting registry API, the very last holdout of untranslated text on users' screens is plugin display names (menu entries for menu type plugins and tab titles for editor type plugins).

In order to translate these as well, we could allow the plugin to set a property on itself that hands us title translations to use dynamically at runtime in an analogous way to the setting registry:

export default class MyPlugin extends HTMLElement {
  constructor() {
    super();
    this.translations = {
      fr: 'Mon Plugin',
      es: 'Mi Complemento',
      nl: 'Mijn Plug-In'
    }
  }
}

Since we cannot technically require a name property with a default English language name to be set on the plugin, the English language fallback name for unavailable translations will be taken directly from the plugin registry file (plugins.json) as has hitherto been the case.

NB since this proposal did not meet our needs regarding namespaced attributes, we amended the definition of our update action to accomodate them.

As with our Wizard API, we would like to move our Action API to a "pure declaration of intent" model:

Sending an EditorActionEvent will simply mean "Please make these changes", with all other implementation details of how the changes are to be made moved into the event listener. The event source can be sure that the action will be committed, no validation of the action will take place prior to committing it. This means it is up to the event source to make sure the action is sensible and will not result in loss of document validity.

This also means no more need to supply old and new properties, and no more need for the event source to differentiate between Create and Move Actions, which are both merged into the new Append action, supplying only the new place (parent and potentially a reference Node) where the Node in question is to appear. Both Append and Remove actions will work on Nodes instead of Elements, only the Update action will still require an Element to be given since only Elements have attributes that could be updated.

interface RemoveActionDetail {
  node: Node;
}

interface InsertActionDetail {
  parent: Node;
  node: Node;
  reference?: Node | null;
}

interface UpdateActionDetail {
  element: Element;
  attributes: Partial<Record<string, string | null>>;
}

Description of new API
#15

When creating a menu plugin for open-scd-core, I was unable to bring the dialog to the foreground in either Firefox or Chrome.

Looking in the Chrome debugger tools, it was (eventually) noticed that the opacity was set to zero on the aside element and the plugin was inheriting this opacity: 0.

This is within the shadow-root of the open-scd element which has the structure:

<mwc-drawer id="menu"></mwc-drawer>
<mwc-dialog id="log"></mwc-dialog>
<aside>
    <oscd-{plugin-hash}>
    <oscd-{plugin-hash}>
    <oscd-{plugin-hash}>
    <oscd-{plugin-hash}>
</aside>

The constructed stylesheet for the aside element was:

aside {
    position: absolute;
    top: 0px;
    left: 0px;
    width: 0px;
    height: 0px;
    overflow: hidden;
    opacity: 0;
    margin: 0px;
    padding: 0px;
}

I resolved this in my plugin with:

  protected firstUpdated(): void {
    this.parentElement?.setAttribute('style', 'opacity: 1');
  }

Which restored visibility operation.

I can't presently see where/how this is set, so I can't do a PR to fix it. However, I will be happy to try with a hint. 😉

With lit2.0 there is a built in mechanism for localization called lit/localize. We would like to use it instead of lit-translate.

NOTE: External plugins will have to take care of their own localization. open-scd-core will provide the BCP 47 language tag standard with setting property.

Load an XMLDocument on incoming OpenDocEvent and update the doc property accordingly.

Currently, I think in plugins we can't identify a new document has been opened even if is the same document (and especially if there have been no edits made).

My testing of a plugin so far suggests that even if edits have been made and I am using editCount with a @state decorator I don't get a re-render (although I may be erring in some fashion).

Filing this issue as requested by Christian.

What we have now:
Non-extensible Settings mixin that saves specific settings and *.nsdoc files to the localStorage and shows settings saved to the localStorage in setting dialog.

What we would like to add:
Allow plugins to register their own settings using an event based API

interface RegisterSettingEventDetail {
   name: string,
   translations: Record<BCP47LanguageTag, string>,
   defaultValue: boolean | string,
   kind: "boolean" | "url" | ... | string[],
}

interface SetSettingEventDetail {
   name: string,
   value: boolean | string,
}

Each plugin then gets a settings property set.

interface Settings {
   language: 'en' | 'de',
   ...,
   darkMode: boolean,
   custom: Partial<Record<string,boolean | string>>,
}

@property()
settings: Settings;

Create a filtered list webcomponent oscd-filtered-list with the same API as filtered-list in open-scd

Open-scd-core is not exporting any typed mixins.
Therefore I cannot use a mixin inside a plugin.

Can these be exported by the foundation as well?

For some weird reason, eslint doesn't know that typescript defines ParentNode. Maybe some version of a typescript-eslint component is too old or something. For now we have an ugly eslint-disable-next-line no-undef workaround at least in mixins/Editing.spec.ts.