docs: add API documentation

[ca-d]

This is our initial draft of an API documentation.

The document is aspirational in nature, meaning it does not reflect the current state of the API, but rather where we would like to be. Code implementing this API is already available in separate branches, so once we have accepted a version of this API doc we can immediately bring the implementation up to speed.

[danyill]

I am delighted to see further API development and pleased to see this timely proposal.
LGTM.

[danyill]

A few more thoughts and perhaps we could get some syntax highlighting fix.

[ca-d]

@danyill I also just added your "plugin bundle archive format" suggestion to the "Missing" section at the bottom.

Like all features which I'd rather implement in a distribution or within a plugin, I added it for completeness of our discussion only, and would suggest removing it from API.md before merging, as soon as we're all agreed that it doesn't belong in core.

[ca-d]

I just removed the "Missing" section from the bottom. If you think any of the points it listed need to be handled by OpenSCD core in particular, please discuss here:

Missing

Plugin manifest, searchable plugin store

This is still needed if we want to enable plugins to be installed and updated from within OpenSCD. This could be done by a "plugin management" or "plugin store" plugin. Otherwise, this could be done by the OpenSCD distribution itself.

A good candidate for a plugin manifest format is the Plugin type defined above, with the addition of a kind flag indicating whether it is a "menu" or "editor" plugin (or maybe "both"), and possibly a version property.

Plugin bundle archive format

For offline installation of plugins (e.g. by dragging and dropping a .zip file into OpenSCD), a format for bundling the plugin's JavaScript and resource files along with a manifest file is needed. This could either be implemented by the OpenSCD distribution or by a "plugin management" plugin as described in the previous section.

Plugin update notifications

Given a plugin manifest with a version number, OpenSCD core could check for updates to the plugins and notify the user when updates are available.

Within the current architecture, the plugin's own service worker is expected to handle this.

Deep linking to editor plugins

Currently, the only way to open an editor plugin is by clicking on its tab in the tab bar. It would be nice to be able to deep link to a particular editor plugin, for example by clicking on a link in another plugin.

This could be handled by the OpenSCD distribution, which could e.g. listen for hashchange events and open the appropriate editor plugin by setting the OpenSCD core's editorIndex property.

[trusz]

I think a lot of the concept are thought through, but I can imagine if you are not familiar with the history some things could harder to understand. For example I don't know why there are no more validator plugins :)

Do you think this is the document to add these reasoning or some other place?

[ca-d]

Do you think this is the document to add these reasoning or some other place?

I think an extra "History" section in the README.md might be a great idea, too. Do you think it would be better to have this section in the API.md?

[trusz]

You could also document the individual decisions as ADR and link them here ;)

[JakobVogelsang]

LGTM

[danyill]

LGTM, thanks for all the discussion, 🎯
Onward to implementation 🚀

[JakobVogelsang]

LGTM

[jarradraumati]

LGTM