From 130636c9ca0769c57cb80b657a4d72300a56d8ef Mon Sep 17 00:00:00 2001 From: Stephen Renwick Date: Fri, 11 Jul 2025 11:30:07 +0200 Subject: [PATCH 1/4] docs: added editor (prop) to the plugin docs --- docs/plugin-api.md | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/plugin-api.md b/docs/plugin-api.md index 3331898..496f3a3 100644 --- a/docs/plugin-api.md +++ b/docs/plugin-api.md @@ -20,6 +20,7 @@ OpenSCD core communicates the data necessary for editing SCL documents by settin ```typescript export default class MyPlugin extends HTMLElement { + editor: Transactor; docs: Record = {}; // all loaded documents doc?: XMLDocument; // the document currently being edited docName?: string; // the current doc's name @@ -28,19 +29,28 @@ export default class MyPlugin extends HTMLElement { } ``` +### `editor` + +`editor` provides a reference to the central editor class used for modifying SCL documents. For +more details on the Transactor (Defaults to XMLEditor). For more on the XMLEditor checkout the [documentation](https://github.com/OMICRONEnergyOSS/oscd-editor) + ### `docs` + `docs` is set to an object mapping `string` keys (document names) to `XMLDocument` values. ### `docName` + The name of the `XMLDocument` currently being edited. ### `doc` + The `XMLDocument` currently being edited. ### `docVersion` 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 @@ -56,20 +66,25 @@ export type EditDetailV2 = { edit: E; title?: string; squash?: boolean; -} +}; -export type EditEventV2 = CustomEvent>; +export type EditEventV2 = CustomEvent< + EditDetailV2 +>; export type EditEventOptions = { title?: string; squash?: boolean; -} +}; -export function newEditEventV2(edit: E, options: EditEventOptions): EditEventV2 { +export function newEditEventV2( + edit: E, + options: EditEventOptions, +): EditEventV2 { return new CustomEvent('oscd-edit-v2', { composed: true, bubbles: true, - detail: {...options, edit}, + detail: { ...options, edit }, }); } @@ -85,15 +100,22 @@ 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. #### `EditV2` type + The `EditDetailV2` defined above contains an `edit` of this type: ```typescript -export type EditV2 = Insert | SetAttributes | SetTextContent | Remove | EditV2[]; +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: > Intent to set or remove (if null) attributes on `element`. + ```typescript export type SetAttributes = { element: Element; @@ -103,6 +125,7 @@ export type SetAttributes = { ``` > Intent to set the `textContent` of `element`. + ```typescript export type SetTextContent = { element: Element; @@ -111,6 +134,7 @@ export type SetTextContent = { ``` > Intent to `parent.insertBefore(node, reference)` + ```typescript export type Insert = { parent: Node; @@ -120,6 +144,7 @@ export type Insert = { ``` > Intent to remove a `node` from its `ownerDocument`. + ```typescript export type Remove = { node: Node; From 23ae57600d5ff3f20b7d4f603c68e91fe621c8c7 Mon Sep 17 00:00:00 2001 From: Stephen Renwick Date: Fri, 11 Jul 2025 12:51:54 +0200 Subject: [PATCH 2/4] chore: fix prettier integration in to eslint --- eslint.config.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/eslint.config.js b/eslint.config.js index fd854a6..16900e7 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -6,6 +6,7 @@ import js from '@eslint/js'; import { FlatCompat } from '@eslint/eslintrc'; import eslintPluginTSDoc from 'eslint-plugin-tsdoc'; import openWcConfig from '@open-wc/eslint-config'; +import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); @@ -86,4 +87,5 @@ export default [ ], }, }, + eslintPluginPrettierRecommended, ]; From 9c4e6b209ea7a1a4c60cc0151fdd0da2a13825fd Mon Sep 17 00:00:00 2001 From: Stephen Renwick Date: Fri, 11 Jul 2025 12:52:59 +0200 Subject: [PATCH 3/4] docs: change plugin prop "docVersion" to "docsState" --- docs/plugin-api.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/plugin-api.md b/docs/plugin-api.md index 496f3a3..4d25bf4 100644 --- a/docs/plugin-api.md +++ b/docs/plugin-api.md @@ -9,6 +9,7 @@ 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, - plugins communicate user intent to OpenSCD core, and - OpenSCD sets CSS fonts and colors for plugins. @@ -17,14 +18,13 @@ The **OpenSCD core API** describes the ways in which: OpenSCD core communicates the data necessary for editing SCL documents by setting the following [properties](https://developer.mozilla.org/en-US/docs/Glossary/Property/JavaScript) on the plugin's [DOM Element](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement): - ```typescript export default class MyPlugin extends HTMLElement { editor: Transactor; 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 + docsState: unknown; // changes value when the document is modified or documents are added/removed. locale: string = 'en'; // the end user's chosen locale } ``` @@ -46,8 +46,9 @@ The name of the `XMLDocument` currently being edited. The `XMLDocument` currently being edited. -### `docVersion` -A change in this property's value indicates a change to the `doc`. +### `docsState` + +A value which changes with edits to the current document AND when documents are opened or closed. ### `locale` From 3de040a1ec72b01f75d694fdc9cb845c36dbdee0 Mon Sep 17 00:00:00 2001 From: Stephen Renwick Date: Fri, 11 Jul 2025 12:54:44 +0200 Subject: [PATCH 4/4] feat: add plugin interface (shell constraint to APIs) --- Plugin.ts | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 Plugin.ts diff --git a/Plugin.ts b/Plugin.ts new file mode 100644 index 0000000..879d819 --- /dev/null +++ b/Plugin.ts @@ -0,0 +1,22 @@ +import { EditV2 } from './editv2.js'; +import { Transactor } from './Transactor.js'; + +/** + * OpenSCD core communicates the data necessary for editing SCL documents by setting the + * following [properties](https://developer.mozilla.org/en-US/docs/Glossary/Property/JavaScript) on + * the plugin's [DOM Element](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) + * + * @property docs - A map of document names to their loaded XMLDocument instances. + * @property doc - The XMLDocument currently being edited, if any. + * @property docName - The name of the currently edited document, if any. + * @property docsState - changes value when the document is modified or documents are added/removed. + * @property locale - The end user's selected locale. + */ +export interface Plugin { + editor: Transactor; + docs: Record; + doc?: XMLDocument; // the document currently being edited + docName?: string; // the current doc's name + docsState: unknown; // current doc's state indicator + locale: string; // the end user's chosen locale +}