From a4c84274ff71797987df1c7281269e2cb5198664 Mon Sep 17 00:00:00 2001 From: Harald Brabenetz Date: Wed, 18 Nov 2026 13:52:35 +0100 Subject: [PATCH 1/2] feat: pass the loaded plugin set into a plugin Add an optional plugins map to Plugin. The tag name is the key and the identity. Shared fields stay on the entry, and distribution-specific values stay in extensions. --- src/Plugin.ts | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ src/oscd-api.ts | 10 +++- 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/src/Plugin.ts b/src/Plugin.ts index 1361a75..a7d6757 100644 --- a/src/Plugin.ts +++ b/src/Plugin.ts @@ -1,6 +1,114 @@ import { EditV2 } from './editv2.js'; import { Transactor } from './Transactor.js'; +/** + * A [BCP 47](https://www.rfc-editor.org/info/bcp47) language tag, for example `en` or `de-AT`. + * + * TypeScript cannot validate that grammar, so this remains a string. A more + * specific tag wins over a broader one: `de-AT`, then `de`, then the US + * English `name` and `description` on the {@link PluginDescriptor}. + */ +export type Bcp47Tag = string; + +/** + * A translation string, or a named group of translation strings. + * Groups may contain further groups, to any depth. + */ +export type TranslationTree = { + [key: string]: string | TranslationTree; +}; + +/** + * The strings for one {@link Bcp47Tag}. + * + * `name` and `description` override the US English fields of the + * {@link PluginDescriptor}. Every other key is a plugin-defined string or a + * nested group, for example `myPlugin.title`. An i18n library that reads + * nested catalogs can load this object as-is. + */ +export interface PluginLocale { + /** Localized plugin name. Overrides {@link PluginDescriptor.name}. */ + name?: string; + + /** Localized description. Overrides {@link PluginDescriptor.description}. */ + description?: string; + + /** Further strings or nested groups for this locale. */ + [message: string]: string | TranslationTree | undefined; +} + +/** + * Kept so descriptions written before `validator` was retired still type-check. + * + * @deprecated Do not use `validator` for a new plugin. It remains only for + * backward compatibility. + */ +export type ValidatorPluginKind = 'validator'; + +/** + * How the host presents a plugin. + * + * `menu` is an action in a menu. `editor` is an editor surface. + * `background` is loaded without its own visible surface. `validator` is + * {@link ValidatorPluginKind} and is deprecated. + */ +export type PluginKind = 'menu' | 'editor' | 'background' | ValidatorPluginKind; + +/** + * One plugin, as passed to a plugin that reads {@link Plugin.plugins}. + * + * The map key is the tag name and is not repeated here. That key is the + * plugin's identity. `src` only says where the host loads it from, so the + * same URL may appear on more than one entry. + */ +export interface PluginDescriptor { + /** US English display name. */ + name: string; + + /** + * URL the host loads this plugin from. + * + * A relative {@link PluginDescriptor.icon} is resolved against this URL. + */ + src: string; + + /** US English description of what the plugin does. */ + description?: string; + + /** + * Icon shown for the plugin. + * + * A Material Symbols identifier, an absolute URL, or a path relative to + * {@link PluginDescriptor.src}. + */ + icon?: string; + + /** + * How the host presents the plugin. + * + * The value `validator` is deprecated and is accepted only so older + * descriptions still type-check. + */ + kind?: PluginKind; + + /** + * Localized strings for this plugin, keyed by {@link Bcp47Tag}. + * + * A more specific tag overrides a broader one, and both override the US + * English `name` and `description` on this descriptor. + */ + translations?: Record; + + /** + * Values outside the shared plugin API. + * + * The key names the owner, for example `CoMPAS`. Only that owner reads the + * value. The shared API does not interpret it, so concerns such as + * `origin` stay here instead of becoming fields of their own. + */ + extensions?: Record; +} + /** * 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 @@ -11,6 +119,7 @@ import { Transactor } from './Transactor.js'; * @property docName - The name of the currently edited document, if any. * @property docVersion - changes value when the document is modified. * @property locale - The end user's selected locale. + * @property plugins - The plugins passed in by the host. Most plugins never read this. */ export interface Plugin { editor: Transactor; @@ -19,4 +128,16 @@ export interface Plugin { docName?: string; // the current doc's name docVersion: unknown; // changes when the document is modified locale: string; // the end user's chosen locale + + /** + * The plugins the host passes in. Only a plugin that must know the whole + * set reads this. The host may omit it. + * + * Each key is the plugin's tag name and is its identity. Write keys as + * slugs: lowercase letters, digits, and `-` only, for example `oscd-ied`. + * + * This is the runtime value. It is not the distribution's plugin list, + * which may describe a different set. + */ + plugins?: Record; } diff --git a/src/oscd-api.ts b/src/oscd-api.ts index 0cce526..8759cc8 100644 --- a/src/oscd-api.ts +++ b/src/oscd-api.ts @@ -33,4 +33,12 @@ export type { export type { OpenDetail, OpenEvent } from './open-event.js'; -export type { Plugin } from './Plugin.js'; +export type { + Bcp47Tag, + Plugin, + PluginDescriptor, + PluginKind, + PluginLocale, + TranslationTree, + ValidatorPluginKind, +} from './Plugin.js'; From c2a3cc9c7851c7786a9acedeaaeccff9ed2f5bfd Mon Sep 17 00:00:00 2001 From: Harald Brabenetz Date: Wed, 18 Nov 2026 14:21:41 +0100 Subject: [PATCH 2/2] feat: make plugin src optional for bundled plugins A plugin compiled into the distribution through an npm dependency has no load URL. A relative icon then resolves against the host URL. --- src/Plugin.ts | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/src/Plugin.ts b/src/Plugin.ts index a7d6757..c91ab8e 100644 --- a/src/Plugin.ts +++ b/src/Plugin.ts @@ -58,8 +58,8 @@ export type PluginKind = 'menu' | 'editor' | 'background' | ValidatorPluginKind; * One plugin, as passed to a plugin that reads {@link Plugin.plugins}. * * The map key is the tag name and is not repeated here. That key is the - * plugin's identity. `src` only says where the host loads it from, so the - * same URL may appear on more than one entry. + * plugin's identity. `src` only says where the host loads a plugin from, so + * the same URL may appear on more than one entry. */ export interface PluginDescriptor { /** US English display name. */ @@ -68,9 +68,14 @@ export interface PluginDescriptor { /** * URL the host loads this plugin from. * + * Omit it when the distribution already includes the plugin through an npm + * dependency. The host does not fetch a URL in that case. The tag name + * remains the identity. + * * A relative {@link PluginDescriptor.icon} is resolved against this URL. + * Without it, a relative icon is resolved against the host URL. */ - src: string; + src?: string; /** US English description of what the plugin does. */ description?: string; @@ -78,8 +83,10 @@ export interface PluginDescriptor { /** * Icon shown for the plugin. * - * A Material Symbols identifier, an absolute URL, or a path relative to - * {@link PluginDescriptor.src}. + * A Material Symbols identifier, an absolute URL, or a relative path. + * A relative path is resolved against {@link PluginDescriptor.src}. When + * `src` is absent, the plugin is part of the host, so the path is resolved + * against the host URL instead. */ icon?: string;