markupeditor 0.9.32 → 0.9.33

package/dist/markup-editor.js

@@ -235,9 +235,14 @@ class Registry {
 
     /**
      * Add `plugin` to the registry, keyed by `name`.
+     * A `plugin` object has `name` and `type` string properties at minimum.
+     * The invoker can add additional properties to the `plugin`.
+     * For example, a `run` function could be part of the `plugin`, which could, 
+     * by convention of the application environment the markupeditor is used in, 
+     * be used to run the `plugin` to perform some action or return something.
      *
-     * @param {object}  plugin  Plugin object with string values for { name, type, filename }.
-     * @param {string}  name    The key used to retrieve and invoke the plugin.
+     * @param {object}  plugin  Plugin object with string properties for {name, type} at minimum.
+     * @param {string}  name    The key used to retrieve and invoke the plugin. Taken from `plugin.name` by default.
      */
     registerPlugin(plugin, name) {
         this._plugins.set(name ?? plugin.name, plugin);
@@ -256,17 +261,17 @@ class Registry {
      * Return the plugin object with `name`, or undefined if not found.
      *
      * @param {string}  name    The key used to identify the plugin.
-     * @returns {object|undefined}
+     * @returns {object | undefined}
      */
     getPlugin(name) {
         return this._plugins.get(name)
     }
 
     /**
-     * Return an array of registered plugins that match type, all if not specified.
-     * Each entry contains {name, type, filename}
+     * Return an array of registered plugins that match `type`, all if not specified.
      *
-     * @returns {Array<{name: string, type: string, filename: string}>}
+     * @param {string}      type    The plugin type to filter by; all plugins are returned if omitted.
+     * @returns {Array<object>}     Array of plugin objects with string properties for {name, type} at minimum.
      */
     getPlugins(type) {
         if (type) {
@@ -512,10 +517,15 @@ const setSelectedID = _registry.setSelectedID.bind(_registry);
 
 /**
  * Add `plugin` to the registry, keyed by `name`.
+ * A `plugin` object has `name` and `type` string properties at minimum.
+ * The invoker can add additional properties to the `plugin`.
+ * For example, a `run` function could be part of the `plugin`, which could, 
+ * by convention of the application environment the markupeditor is used in, 
+ * be used to run the `plugin` to perform some action or return something.
  *
  * @function
- * @param {object}  plugin  Plugin object with string values for { name, type, filename }.
- * @param {string}  name    The key used to retrieve and invoke the plugin.
+ * @param {object}  plugin  Plugin object with string properties for {name, type} at minimum.
+ * @param {string}  name    The key used to retrieve and invoke the plugin. Taken from `plugin.name` by default.
  */
 const registerPlugin = _registry.registerPlugin.bind(_registry);
 
@@ -538,14 +548,36 @@ const getPlugin = _registry.getPlugin.bind(_registry);
 
 /**
  * Return an array of registered plugins that match `type`, all if not specified.
- * Each entry contains {name, type, filename}
  *
  * @function
- * @param {string}  [type]  The plugin type to filter by; all plugins are returned if omitted.
- * @returns {Array<{name: string, type: string, filename: string}>}
+ * @param {string}      type    The plugin type to filter by; all plugins are returned if omitted.
+ * @returns {Array<object>}     Array of plugin objects with string properties for {name, type} at minimum.
  */
 const getPlugins = _registry.getPlugins.bind(_registry);
 
+/**
+ * Look up the plugin with `name` and invoke its `run` function, returning/awaiting whatever
+ * it resolves to.
+ *
+ * Content-agnostic and plugin-type-agnostic: `runPlugin` never fetches or supplies content
+ * on the plugin's behalf. The plugin's `run` function is responsible for getting
+ * whatever content it needs, via whichever accessor (e.g. `getHTML`) fits its purpose.
+ *
+ * Returns `null`, never rejects, when there's nothing to run: no plugin registered with
+ * `name`, or a plugin registered without a `run` function. If `run` itself rejects, that
+ * rejection propagates unchanged — it is not swallowed into `null`, so a caller can't
+ * confuse "nothing to run" with "the plugin failed."
+ *
+ * @function
+ * @param {string}  name    The key used to identify the plugin.
+ * @returns {Promise<*>}    Whatever `plugin.run()` resolves to, or `null`.
+ */
+async function runPlugin(name) {
+    const plugin = getPlugin(name);
+    if (!plugin?.run) return null
+    return await plugin.run()
+}
+
 /**
  * MUError captures internal errors and makes it easy to communicate them externally.
  *
@@ -42563,6 +42595,7 @@ const MU = {
     unregisterPlugin,
     getPlugin,
     getPlugins,
+    runPlugin,
 };
 
 sheet.media.mediaText = '(prefers-color-scheme: dark)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markupeditor",
-  "version": "0.9.32",
+  "version": "0.9.33",
   "description": "A web component and API for WYSIWYG HTML editing.",
   "keywords": [
     "wysiwyg",