From e0b440c0b816bd56fcf4fd5845edfdfebac09be2 Mon Sep 17 00:00:00 2001 From: cad Date: Tue, 22 Apr 2025 13:33:49 +0200 Subject: [PATCH] docs(API): remove plugin management --- API.md => docs/API.plugins.md | 93 +++++------------------------------ 1 file changed, 12 insertions(+), 81 deletions(-) rename API.md => docs/API.plugins.md (67%) diff --git a/API.md b/docs/API.plugins.md similarity index 67% rename from API.md rename to docs/API.plugins.md index 17dd7bf..a60a239 100644 --- a/API.md +++ b/docs/API.plugins.md @@ -1,4 +1,4 @@ -# OpenSCD core API +# OpenSCD core API for plugins ## Overview @@ -6,11 +6,7 @@ **OpenSCD core** is the central supervisory component which coordinates the work of all the plugins, allowing them to work together in editing the same SCL document. -An **OpenSCD plugin** is a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) which exports a particular [custom element class](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#implementing_a_custom_element) as its [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#default_exports_versus_named_exports). OpenSCD core imports the module, registers its custom element under a uniquely generated tag name, and finally renders a new element with that tag name into the app. - -An **OpenSCD menu plugin** is an OpenSCD plugin with an additional `run()` instance method which is called when the plugin's entry is clicked in OpenSCD's menu. It is continuously rendered into the app and is expected to normally not display any content of its own. It is meant for one-shot editing tasks or tasks that always run in the background (like validation). - -An **OpenSCD editor plugin** is a OpenSCD plugin that is only rendered as long as the user has its tab selected in OpenSCD's tab bar. It is meant for rendering the main part of OpenSCD's user interface. +An **OpenSCD plugin** is a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#implementing_a_custom_element) that has been registered in the global [`customElements`](https://developer.mozilla.org/en-US/docs/Web/API/Window/customElements) registry under some tag name. OpenSCD core renders an element with that tag name into the app. The component may optionally provide a `run()` method for OpenSCD core to call in order to trigger an action. The **OpenSCD core API** describes the ways in which: - OpenSCD core communicates relevant data to the plugins, @@ -24,42 +20,15 @@ OpenSCD core communicates the data necessary for editing SCL documents by settin ```typescript export default class MyPlugin extends HTMLElement { - docs: Record = {}; - doc?: XMLDocument; - docName?: string; - editable: string[] = [ - 'cid', - 'icd', - 'iid', - 'scd', - 'sed', - 'ssd', - ]; - history: LogEntry[]; - editCount: number = 0; - plugins: { menu: Plugin[], editor: Plugin[] }[]; - locale: string = 'en'; -} - -/** Helper types exported by OpenSCD core **/ - -type LogEntry = { - redo: Edit; // `Edit` defined below - undo: Edit; - title?: string -} - -type Plugin = { - name: string; - translations?: Record; - src: string; - icon: string; // Material icon name or image URL - requireDoc?: boolean; // disable plugin if no doc is opened + docs: Record = {}; // all loaded documents + doc?: XMLDocument; // the document currently being edited + docName?: string; // the current doc's name + docVersion: unknown; // current doc's state indicator + locale: string = 'en'; // the end user's chosen locale } ``` ### `docs` - `docs` is set to an object mapping `string` keys (document names) to `XMLDocument` values. ### `docName` @@ -68,22 +37,10 @@ The name of the `XMLDocument` currently being edited. ### `doc` The `XMLDocument` currently being edited. -### `editable` -Filename extensions of user-editable documents. - -### `history` -History of edits done to `doc`. - ### `docVersion` - -A change in the property indicates a change to the `doc` as a result of edits (including undo and redo). - -### `plugins` - -Arrays of `Plugin` objects describing the currently loaded `menu` and `editor` plugins, respectively. +A change in this property's value indicates a change to the `doc`. ### `locale` - Selected language (IETF language tag). ## Communicating user intent to OpenSCD core @@ -123,16 +80,15 @@ declare global { } ``` -Its `title` property is a human-readable description of the edit for displaying in the editing history dialog. +Its `title` property is a human-readable description of the edit. The `squash` flag indicates whether the edit should be merged with the previous edit in the history. #### `Edit` type - The `EditDetailV2` defined above contains an `edit` of this type: ```typescript -export type EditV2 = Insert | SetAttributes | SetTextContent | Remove | Edit[]; +export type EditV2 = Insert | SetAttributes | SetTextContent | Remove | EditV2[]; ``` This means that a single edit can either consist in a sequence of other edits or in one of the following atomic edit types: @@ -204,7 +160,7 @@ The **wizard event** allows the plugin to request opening a modal dialog enablin ```typescript /* eslint-disable no-undef */ interface WizardRequestBase { - subWizard?: boolean; + subWizard?: boolean; // TODO: describe what this currently means } export interface EditWizardRequest extends WizardRequestBase { @@ -277,30 +233,6 @@ declare global { } ``` -### `ConfigurePluginEvent` - -The **configure plugin event** allows the plugin to request that OpenSCD core add, remove, or reconfigure a plugin. - -```typescript -export type ConfigurePluginDetail = { - name: string; - kind: 'menu' | 'editor'; - config: Plugin | null; -}; - -export type ConfigurePluginEvent = CustomEvent; - -export function newConfigurePluginEvent(name: string, kind: 'menu' | 'editor', config: Plugin | null): ConfigurePluginEvent { - return new CustomEvent('oscd-configure-plugin', { - bubbles: true, - composed: true, - detail: { name, kind, config }, - }); -} -``` - -The combination of `name` and `kind` uniquely identifies the plugin to be configured. If `config` is `null`, the plugin is removed. Otherwise, the plugin is added or reconfigured. - ## Theming OpenSCD core sets the following CSS variables on the plugin: @@ -321,8 +253,7 @@ OpenSCD core sets the following CSS variables on the plugin: --oscd-base3: var(--oscd-theme-base3, #fdf6e3); --oscd-text-font: var(--oscd-theme-text-font, 'Roboto'); + --oscd-text-font-mono: var(--oscd-theme-text-font-mono, 'Roboto Mono'); --oscd-icon-font: var(--oscd-theme-icon-font, 'Material Icons'); } ``` - -It is expected that the fonts `--oscd-theme-text-font` and `--oscd-theme-icon-font` will be loaded in OpenSCD's `index.html` file. OpenSCD core does not load any fonts by itself.