@brightspace-ui/core 2.161.1 → 2.162.0

package/helpers/README.md

@@ -187,6 +187,45 @@ import { getLegacyOffsetParent } from '@brightspace-ui/core/helpers/offsetParent
 const offsetParent = getLegacyOffsetParent(element);
 ```
 
+## Plugins
+
+Plugin helpers provide a way for modules to implement and register objects that can be plugged into other project's modules without requiring the plugin consumer to import those modules or objects directly. A higher order module (ex. in BSI) is responsible for importing the plugin registrations.
+
+The plugin implementor uses the `registerPlugin` helper method to make its implementation available to interested consumers. The implementor provides a key for the set of plugins in which to register and the plugin implementation.
+
+Optionally, an object to specify a `key` for the plugin and/or the `sort` value may be provided. The `key` is useful if consumers intend to request a specific plugin, while the `sort` is useful in cases where the order of plugins is important to consumers. If `sort` is not specified for at least one plugin, they will be provided to consumers in registration order.
+
+**Important!** plugin registrations should defer loading their dependencies using dynamic imports. They should **not** be synchronously imported in the registration module.
+
+```js
+import { registerPlugin } from '@brightspace-ui/core/helpers/plugins.js';
+
+// Provide plugin set key, plugin
+registerPlugin('foo-plugins', { prop1: 'some value' });
+registerPlugin('foo-plugins', { prop1: 'other value' });
+
+// Optionally provide key and/or sort value
+registerPlugin('foo-plugins', { prop1: 'some value' }, { key: 'key-1', sort: 1 });
+registerPlugin('foo-plugins', { prop1: 'other value' }, { key: 'key-2', sort: 2 });
+
+// Defer loading dependencies until needed
+registerPlugin('foo-plugins', { getRenderer: async () => {
+    return (await import('./some-module.js')).renderer
+}});
+```
+
+The plugin consumer uses the `getPlugins` helper method to get references to the registered plugins by providing a key for the set of plugins. If the consumer knows the key of the plugin it needs, it can request the plugin by using `tryGetPluginByKey` and specifying the plugin set key and plugin key.
+
+```js
+import { getPlugins, tryGetPluginByKey } from '@brightspace-ui/core/helpers/plugins.js';
+
+// Call getPlugins to get plugins
+const plugins = getPlugins('foo-plugins');
+
+// Call tryGetPluginByKey to get a specific plugin by key
+const plugin = tryGetPluginByKey('foo-plugins', 'key-1');
+```
+
 ## queueMicrotask
 
 A polyfill for [queueMicrotask](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/queueMicrotask). For more information on microtasks, read [this article from Mozilla](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide).

package/helpers/plugins.js

@@ -0,0 +1,46 @@
+const pluginSets = new Map();
+
+function getPluginSet(setKey) {
+	let pluginSet = pluginSets.get(setKey);
+	if (pluginSet) return pluginSet;
+
+	pluginSet = { plugins: [], requested: false, requiresSorting: false };
+	pluginSets.set(setKey, pluginSet);
+	return pluginSet;
+}
+
+export function getPlugins(setKey) {
+	const pluginSet = getPluginSet(setKey);
+	pluginSet.requested = true;
+	if (pluginSet.requiresSorting) {
+		pluginSet.plugins.sort((item1, item2) => item1.options.sort - item2.options.sort);
+		pluginSet.requiresSorting = false;
+	}
+	return pluginSet.plugins.map(item => item.plugin);
+}
+
+export function registerPlugin(setKey, plugin, options) {
+	const pluginSet = getPluginSet(setKey);
+
+	if (pluginSet.requested) {
+		throw new Error(`Plugin Set "${setKey}" has already been requested. Additional plugin registrations would result in stale consumer plugins.`);
+	} else if (options?.key !== undefined) {
+		if (pluginSet.plugins.find(registeredPlugin => registeredPlugin.options.key === options?.key)) {
+			throw new Error(`Plugin Set "${setKey}" already has a plugin with the key "${options.key}".`);
+		}
+	}
+
+	pluginSet.plugins.push({ plugin, options: Object.assign({ key: undefined, sort: 0 }, options) });
+	pluginSet.requiresSorting = pluginSet.requiresSorting || (options?.sort !== undefined);
+}
+
+// Do not import! Testing only!!
+export function resetPlugins() {
+	pluginSets.clear();
+}
+
+export function tryGetPluginByKey(setKey, pluginKey) {
+	const pluginSet = pluginSets.get(setKey);
+	const plugin = pluginSet?.plugins.find(plugin => plugin.options.key === pluginKey)?.plugin;
+	return plugin || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "2.161.1",
+  "version": "2.162.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",