@cocreate/plugins 1.8.0 → 2.0.0

package/src/index.js

@@ -2,13 +2,18 @@ import Observer from '@cocreate/observer';
 import { astAsync } from '@cocreate/utils';
 
 const scriptCache = new Map();
-const cssMarker = typeof document !== 'undefined' 
+const pendingElements = new WeakSet();
+const initializedPlugins = new WeakMap();
+const initializingPlugins = new WeakMap();
+const cssMarker = typeof document !== 'undefined'
     ? document.head.querySelector('meta[name="viewport"]') || document.head.lastChild 
     : null;
 
 /**
  * Retrieves the global plugin configuration object from window.CoCreateConfig.
  * @returns {Object}
+ * @private
+ * @environment client
  */
 function getPluginsConfig() {
     if (typeof window !== 'undefined' && window.CoCreateConfig && window.CoCreateConfig.plugins) {
@@ -21,6 +26,8 @@ function getPluginsConfig() {
  * Dynamically registers or updates a plugin definition in global config.
  * @param {string} name - Plugin identifier
  * @param {Object} config - Plugin configuration object (js, css, etc.)
+ * @public
+ * @environment client
  */
 export function registerPlugin(name, config) {
     if (typeof window !== 'undefined') {
@@ -35,6 +42,8 @@ export function registerPlugin(name, config) {
  * Sets crossOrigin="anonymous" by default for simple string URLs.
  * @param {string|Object} item - Script URL or object with configuration
  * @returns {Promise<void>}
+ * @private
+ * @environment client
  */
 function loadScript(item) {
     const src = typeof item === 'string' ? item : item?.src;
@@ -74,6 +83,8 @@ function loadScript(item) {
  * Sets crossOrigin="anonymous" by default for simple string URLs.
  * @param {string|Object} item - Stylesheet URL or object with configuration
  * @returns {Promise<void>}
+ * @private
+ * @environment client
  */
 function loadCSS(item) {
     const href = typeof item === 'string' ? item : item?.href;
@@ -110,8 +121,11 @@ function loadCSS(item) {
 
 /**
  * Preloads JS scripts and CSS stylesheets declared in global plugins config.
- * Runs in parallel using Promise.allSettled.
+ * Loads each plugin's JavaScript resources in declared order while allowing
+ * independent plugins and stylesheets to load in parallel.
  * @param {Array<string>} pluginNames - Names of target plugins to preload
+ * @private
+ * @environment client
  */
 async function preloadResources(pluginNames) {
     const plugins = getPluginsConfig();
@@ -126,7 +140,11 @@ async function preloadResources(pluginNames) {
             }
             if (config.js) {
                 const jsFiles = Array.isArray(config.js) ? config.js : [config.js];
-                jsFiles.forEach(src => promises.push(loadScript(src)));
+                promises.push((async () => {
+                    for (const src of jsFiles) {
+                        await loadScript(src);
+                    }
+                })());
             }
         }
     }
@@ -145,6 +163,8 @@ async function preloadResources(pluginNames) {
  * @param {number} retries - Number of retries
  * @param {number} delay - Retry interval in ms
  * @returns {Promise<Function|Object|null>}
+ * @private
+ * @environment client
  */
 async function waitForPluginOnWindow(pluginName, retries = 5, delay = 50) {
     for (let i = 0; i < retries; i++) {
@@ -159,6 +179,8 @@ async function waitForPluginOnWindow(pluginName, retries = 5, delay = 50) {
  * Helper to resolve and normalize plugin library constructor from window object.
  * @param {string} pluginName - The target plugin identifier
  * @returns {Function|Object|null}
+ * @private
+ * @environment client
  */
 function getPluginLibrary(pluginName) {
     if (typeof window === 'undefined') return null;
@@ -171,18 +193,53 @@ function getPluginLibrary(pluginName) {
     return null;
 }
 
+function getPluginNames(configBlock) {
+    const configuredPlugins = getPluginsConfig();
+    const pluginNames = new Set();
+
+    function collect(value) {
+        if (!value || typeof value !== 'object') return;
+
+        for (const [key, childValue] of Object.entries(value)) {
+            const name = key.replace(/^\$/, '').split('.')[0];
+            if (configuredPlugins[name] || getPluginLibrary(name)) {
+                pluginNames.add(name);
+            }
+            collect(childValue);
+        }
+    }
+
+    collect(configBlock);
+
+    return pluginNames;
+}
+
 /**
  * Parses element 'plugin' attribute, executes AST configuration via astAsync,
- * sets core library on window, and attaches instance onto element property.
+ * with result storage controlled explicitly by the AST configuration.
  * @param {Element} el - DOM element with plugin attribute
+ * @private
+ * @environment client
  */
-async function processPlugin(el) {
-    if (!el || !el.attributes) return;
+function processPlugin(el) {
+    if (!el || !el.attributes) return Promise.resolve();
 
     const pluginAttrNode = el.attributes['plugin'] || el.attributes.getNamedItem?.('plugin');
     const rawPluginAttr = pluginAttrNode?.value?.trim();
-    if (!rawPluginAttr) return;
+    if (!rawPluginAttr) return Promise.resolve();
+
+    const pending = initializingPlugins.get(el);
+    if (pending?.value === rawPluginAttr) return pending.promise;
+    if (initializedPlugins.get(el) === rawPluginAttr) return Promise.resolve();
+
+    const promise = initializePlugin(el, rawPluginAttr).finally(() => {
+        if (initializingPlugins.get(el)?.promise === promise) initializingPlugins.delete(el);
+    });
+    initializingPlugins.set(el, { value: rawPluginAttr, promise });
+    return promise;
+}
 
+async function initializePlugin(el, rawPluginAttr) {
     try {
         let configs = [];
 
@@ -190,65 +247,41 @@ async function processPlugin(el) {
             const parsedConfig = JSON.parse(rawPluginAttr);
             configs = Array.isArray(parsedConfig) ? parsedConfig : [parsedConfig];
         } else {
-            configs = [{ [rawPluginAttr]: [] }];
+            configs = [{ ['$' + rawPluginAttr.replace(/^\$/, '')]: [] }];
         }
 
-        const targetPlugins = new Set();
-        configs.forEach(conf => {
-            Object.keys(conf).forEach(k => {
-                if (!k.startsWith('\u0024')) {
-                    targetPlugins.add(k.split('.')[0]);
-                }
-            });
-        });
+        const configPlans = configs.map(configBlock => ({
+            configBlock,
+            pluginNames: getPluginNames(configBlock)
+        }));
+        const targetPlugins = new Set(
+            configPlans.flatMap(({ pluginNames }) => Array.from(pluginNames))
+        );
 
         await preloadResources(Array.from(targetPlugins));
 
-        for (const configBlock of configs) {
-            for (const [pluginName, astValue] of Object.entries(configBlock)) {
-                // Poll window to ensure script execution has completed
-                const pluginLib = await waitForPluginOnWindow(pluginName);
-
-                // Ensure plugin library definition is attached to window once loaded
-                if (pluginLib && typeof window !== 'undefined' && !window[pluginName]) {
-                    window[pluginName] = pluginLib;
-                }
+        for (const { configBlock, pluginNames } of configPlans) {
+            const libraries = {};
 
-                // Format operator key with $ for AST engine recognition (e.g. SimpleBar -> $SimpleBar)
-                const operatorName = pluginName.startsWith('\u0024') ? pluginName : `$${pluginName}`;
-
-                // Create constructor wrapper to safely instantiate class/function
-                const opWrapper = function(params) {
-                    const args = Array.isArray(params) ? params : [params];
-                    if (typeof pluginLib === 'function') {
-                        try {
-                            return new pluginLib(...args);
-                        } catch (e) {
-                            return pluginLib(...args);
-                        }
-                    }
-                    return pluginLib;
-                };
-
-                // Provide operator wrapper in context for AST registry lookup
-                const context = {
-                    [operatorName]: opWrapper
-                };
-
-                // Execute AST with the $ operator key so astAsync invokes operatorKey logic
-                const result = await astAsync({
-                    node: el,
-                    sandbox: context,
-                    executeAST: { [operatorName]: astValue }
-                });
-
-                if (result !== undefined && !pluginName.startsWith('\u0024')) {
-                    // Attach returned plugin instance directly onto element property
-                    el[pluginName] = result;
+            for (const pluginName of pluginNames) {
+                const library = await waitForPluginOnWindow(pluginName);
+                if (!library) {
+                    throw new Error(`Plugin '${pluginName}' is not available on window.`);
                 }
+                libraries['$' + pluginName] = library;
             }
+
+            const scope = { ...libraries, $this: el };
+
+            await astAsync({
+                executeAST: configBlock,
+                sandbox: scope,
+                node: el
+            });
         }
+        initializedPlugins.set(el, rawPluginAttr);
     } catch (err) {
+        initializedPlugins.delete(el);
         console.error('[Plugin System] Failed to parse and execute plugin configuration:', err, rawPluginAttr);
     }
 }
@@ -256,23 +289,37 @@ async function processPlugin(el) {
 /**
  * Initializes plugins on single elements, collections, or selector query matches.
  * @param {Element|NodeList|Array|string} elements - Target element(s) or DOM query selector
+ * @public
+ * @environment client
  */
 export function init(elements) {
-    if (!elements) return;
+    if (!elements) return Promise.resolve([]);
 
     if (typeof elements === 'string') {
         elements = document.querySelectorAll(elements);
     }
 
     if (elements instanceof Element) {
-        processPlugin(elements);
+        return processPlugin(elements);
     } else if (elements.length !== undefined || Array.isArray(elements)) {
-        Array.from(elements).forEach(el => {
-            if (el instanceof Element) {
-                processPlugin(el);
-            }
-        });
+        return Promise.all(
+            Array.from(elements)
+                .filter(el => el instanceof Element)
+                .map(el => processPlugin(el))
+        );
     }
+
+    return Promise.resolve([]);
+}
+
+function scheduleInit(element) {
+    if (!element || pendingElements.has(element)) return;
+
+    pendingElements.add(element);
+    requestAnimationFrame(() => {
+        pendingElements.delete(element);
+        if (element.isConnected) init(element);
+    });
 }
 
 if (typeof document !== 'undefined') {
@@ -282,10 +329,42 @@ if (typeof document !== 'undefined') {
         types: ["addedNodes", "attributes"],
         selector: selector,
         attributeFilter: ["plugin"],
-        callback: (mutation) => init(mutation.target)
+        callback: (mutation) => {
+            scheduleInit(mutation.target);
+        }
     });
 
     init(document.querySelectorAll(selector));
 }
 
-export default { init, registerPlugin };
+export default { init, registerPlugin };
+
+/**
+ *
+ * @name plugin
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ * CoCreate plugins
+ *
+ * @module plugins
+ * @environment client
+ */
+
+/**
+ * Declarative selectors recognized by this module.
+ *
+ * @name declarative-selectors
+ * @kind member
+ * @selectors
+ * @environment client
+ * @example
+ * ```json
+ * [
+ *   "[plugin]"
+ * ]
+ * ```
+ */

package/test/result-storage.test.js

@@ -0,0 +1,212 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import vm from 'node:vm';
+import test from 'node:test';
+import { astAsync } from '@cocreate/utils';
+
+const code = fs.readFileSync(new URL('../src/index.js', import.meta.url), 'utf8')
+    .replace(/^import .*;\r?\n/gm, '')
+    .replace(/^export /gm, '')
+    .replace('default { init, registerPlugin };', 'globalThis.pluginInit = init;');
+
+class Element {
+    constructor(config) {
+        this.attributes = { plugin: { value: typeof config === 'string' ? config : JSON.stringify(config) } };
+    }
+}
+
+function runtime(libraries, evaluate = astAsync) {
+    const errors = [];
+    const context = {
+        astAsync: evaluate, Element,
+        window: { ...libraries, Object },
+        console: { error: (...args) => errors.push(args), warn: (...args) => errors.push(args) }
+    };
+    vm.runInNewContext(code, context);
+    return {
+        async init(element) {
+            await context.pluginInit(element);
+            assert.deepEqual(errors, []);
+        }
+    };
+}
+
+test('bare plugin initialization does not attach its returned instance', async () => {
+    let calls = 0;
+    class ExamplePlugin {
+        constructor() { calls++; }
+    }
+    const app = runtime({ ExamplePlugin });
+    const el = new Element('ExamplePlugin');
+    await app.init(el);
+    await app.init(el);
+    assert.equal(calls, 1);
+    assert.equal(Object.hasOwn(el, 'ExamplePlugin'), false);
+});
+
+test('nested constructors and $return results do not attach automatically', async () => {
+    class Widget {}
+    const app = runtime({ Library: { Widget } });
+    for (const config of [
+        { '$Library.Widget': [] },
+        { $return: { '$Library.Widget': [] } }
+    ]) {
+        const el = new Element(config);
+        await app.init(el);
+        assert.equal(Object.hasOwn(el, 'Library'), false);
+    }
+});
+
+test('AST can explicitly store a returned instance on $this under a chosen key', async () => {
+    class ExamplePlugin {}
+    const app = runtime({ ExamplePlugin });
+    const el = new Element({
+        '$this.customInstance': { $ExamplePlugin: [] }
+    });
+    await app.init(el);
+    assert.ok(el.customInstance instanceof ExamplePlugin);
+    assert.equal(Object.hasOwn(el, 'ExamplePlugin'), false);
+});
+
+test('AST can store results elsewhere and call methods on explicit references', async () => {
+    class ExamplePlugin {
+        render() { this.rendered = true; }
+    }
+    const destination = {};
+    const app = runtime({ ExamplePlugin, destination });
+    const el = new Element({
+        instance: { $ExamplePlugin: [] },
+        '$instance.render': [],
+        $return: { '$destination': { '$Object.assign': ['$destination', { instance: '$instance' }] } }
+    });
+    await app.init(el);
+    assert.ok(destination.instance instanceof ExamplePlugin);
+    assert.equal(destination.instance.rendered, true);
+    assert.equal(Object.hasOwn(el, 'ExamplePlugin'), false);
+    assert.equal(Object.hasOwn(el, 'instance'), false);
+});
+
+test('subsequent operations keep referencing a global library after a call returns a value', async () => {
+    let calls = 0;
+    function GlobalPlugin() { return {}; }
+    GlobalPlugin.highlightAll = () => { calls++; };
+    const app = runtime({ GlobalPlugin });
+    const el = new Element({ '$GlobalPlugin': [], '$GlobalPlugin.highlightAll': [] });
+    await app.init(el);
+    assert.equal(calls, 1);
+    assert.equal(Object.hasOwn(el, 'GlobalPlugin'), false);
+});
+
+test('passes the entire unchanged configuration to AST once with the host and library scope', async () => {
+    const config = {
+        created: { $ExamplePlugin: ['$this'] },
+        '$this.instance': '$created',
+        '$this.instance.render': []
+    };
+    class ExamplePlugin {
+        constructor(host) { this.host = host; }
+        render() { this.rendered = true; }
+    }
+    const calls = [];
+    const app = runtime({ ExamplePlugin }, async options => {
+        calls.push(options);
+        return astAsync(options);
+    });
+    const el = new Element(config);
+    await app.init(el);
+    assert.equal(calls.length, 1);
+    assert.deepEqual(JSON.parse(JSON.stringify(calls[0].executeAST)), config);
+    assert.equal(calls[0].sandbox.$this, el);
+    assert.equal(calls[0].sandbox.$ExamplePlugin, ExamplePlugin);
+    assert.equal(calls[0].node, el);
+    assert.ok(el.instance instanceof ExamplePlugin);
+    assert.equal(el.instance.host, el);
+    assert.equal(el.instance.rendered, true);
+});
+
+test('plain keys store data rather than being rewritten into plugin calls', async () => {
+    let calls = 0;
+    function ExamplePlugin() { calls++; }
+    const app = runtime({ ExamplePlugin });
+    const el = new Element({
+        ExamplePlugin: ['configuration data'],
+        '$this.saved': '$ExamplePlugin'
+    });
+    await app.init(el);
+    assert.equal(calls, 0);
+    assert.equal(el.saved, ExamplePlugin);
+});
+
+test('configuration blocks execute in order without special treatment for $return', async () => {
+    const order = [];
+    function ExamplePlugin(value) { order.push(value); return value; }
+    const app = runtime({ ExamplePlugin });
+    const el = new Element([
+        { '$this.first': { $ExamplePlugin: ['first'] } },
+        { $return: { '$this.second': { $ExamplePlugin: ['$this.first'] } } }
+    ]);
+    await app.init(el);
+    assert.deepEqual(order, ['first', 'first']);
+    assert.equal(el.first, 'first');
+    assert.equal(el.second, 'first');
+    assert.equal(Object.hasOwn(el, 'ExamplePlugin'), false);
+});
+
+test('concurrent initialization calls await the same pending setup', async () => {
+    let release;
+    let entered;
+    let calls = 0;
+    const gate = new Promise(resolve => { release = resolve; });
+    const started = new Promise(resolve => { entered = resolve; });
+    const app = runtime({ ExamplePlugin() {} }, async args => {
+        calls++;
+        entered();
+        await gate;
+        return astAsync(args);
+    });
+    const element = new Element('ExamplePlugin');
+    const first = app.init(element);
+    await started;
+    let secondFinished = false;
+    const second = app.init(element).then(() => { secondFinished = true; });
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.equal(secondFinished, false);
+    assert.equal(calls, 1);
+    release();
+    await Promise.all([first, second]);
+    assert.equal(secondFinished, true);
+    await app.init(element);
+    assert.equal(calls, 1);
+});
+
+test('a plugin can await another initializer before connecting its result', async () => {
+    let release;
+    let entered;
+    let connected = false;
+    const gate = new Promise(resolve => { release = resolve; });
+    const started = new Promise(resolve => { entered = resolve; });
+    const markdown = new Element({ '$this.parser': { $Parser: [] } });
+    const CoCreate = { plugins: { init: () => app.init(markdown) } };
+    const app = runtime({
+        CoCreate,
+        async Parser() {
+            entered();
+            await gate;
+            return { ready: true };
+        },
+        connect() {
+            assert.equal(markdown.parser.ready, true);
+            connected = true;
+        }
+    });
+    const prism = new Element({ '$CoCreate.plugins.init': ['#markdown'], $connect: [] });
+    const first = app.init(markdown);
+    await started;
+    const second = app.init(prism);
+    await Promise.resolve();
+    assert.equal(connected, false);
+    release();
+    await Promise.all([first, second]);
+    assert.equal(connected, true);
+});

package/webpack.config.js

@@ -1,9 +1,13 @@
-const path = require("path");
-const MiniCssExtractPlugin = require("mini-css-extract-plugin");
-const { EsbuildPlugin } = require("esbuild-loader");
-const { FileUploader } = require("@cocreate/webpack");
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import MiniCssExtractPlugin from "mini-css-extract-plugin";
+import { EsbuildPlugin } from "esbuild-loader";
+import webpackPackage from "@cocreate/webpack";
 
-module.exports = async (env, argv) => {
+const { FileUploader } = webpackPackage;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default async (env, argv) => {
 	const isProduction = argv && argv.mode === "production";
 	const config = {
 		entry: {
@@ -52,7 +56,7 @@ module.exports = async (env, argv) => {
 				})
 			],
 			splitChunks: {
-				pluginsGroups: {
+				cacheGroups: {
 					defaultVendors: false
 				}
 			}