diff --git a/src/Plugin.ts b/src/Plugin.ts index 1361a75..c91ab8e 100644 --- a/src/Plugin.ts +++ b/src/Plugin.ts @@ -1,6 +1,121 @@ 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 a plugin 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. + * + * 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; + + /** US English description of what the plugin does. */ + description?: string; + + /** + * Icon shown for the plugin. + * + * 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; + + /** + * 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 +126,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 +135,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';