@cocreate/events 1.36.0 → 2.0.0

package/src/index.js

@@ -18,14 +18,29 @@
 // Commercial Licensing Information:
 // For commercial use of this software without the copyleft provisions of the AGPLv3,
 // you must obtain a commercial license from CoCreate LLC.
-// For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
+// For details, visit <https://CoCreateJS.com/licenses/> or contact us at sales@CoCreateJS.com.
 
-import { queryElements } from "@cocreate/utils";
+import { queryElements, resolveProperty, astAsync } from "@cocreate/utils";
 import action from "@cocreate/actions";
 import observer from "@cocreate/observer";
 import "@cocreate/element-prototype";
 import { getAttribute } from "@cocreate/element-prototype/src/getAttribute.js";
 
+function resolvePropertyPath(object, path) {
+    const segments = path.split(".");
+    let target = object;
+
+    for (let index = 0; index < segments.length; index++) {
+        if (target == null) return null;
+        const key = resolveProperty(target, segments[index]) || segments[index];
+        if (index === segments.length - 1)
+            return { target, key, value: target[key] };
+        target = target[key];
+    }
+
+    return null;
+}
+
 const CoCreateEvents = {
     elements: new Map(),
 
@@ -50,6 +65,11 @@ const CoCreateEvents = {
         "save"
     ],
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     init: function (prefix, events) {
         if (prefix && events) {
             this.initPrefix(prefix, events);
@@ -111,6 +131,11 @@ const CoCreateEvents = {
         });
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     initPrefix: function (prefix, events) {
         action.init({
             name: prefix,
@@ -129,11 +154,11 @@ const CoCreateEvents = {
         // Updated selector to use dash for options: prefix-group, prefix-query
         const knownTargets = this.knownTargets.map(target => `[${prefix}\\.${target}]`);
         const selector = [
-            `[${prefix}]`,
-            `[${prefix}-group]`,
-            `[${prefix}-query]`,
-            `[${prefix}-element]`,
-            ...knownTargets
+            `[${prefix}]`,
+            `[${prefix}-group]`,
+            `[${prefix}-query]`,
+            `[${prefix}-element]`,
+            ...knownTargets
         ].join(", ");
 
         observer.init({
@@ -151,10 +176,20 @@ const CoCreateEvents = {
             }
         });
 
+        /**
+         *
+ * @public
+ * @environment client
+ */
         const elements = document.querySelectorAll(selector);
         this.initElements(elements, prefix, events);
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     initElements: function (elements, prefix, events = []) {
         for (const el of elements) {
             let isEventable = true;
@@ -235,11 +270,26 @@ const CoCreateEvents = {
 
             const prefixData = elData[prefix];
 
+            // A new checked state must propagate even after an earlier
+            // input/change event; CRUD updates use the same event path.
+            const selectionChanged =
+                (target.type === "checkbox" || target.type === "radio") &&
+                prefixData.checked !== target.checked;
+            if (
+                event.detail?.skip === true && prefixData.prev === event.type &&
+                ["input", "change"].includes(event.type) && !selectionChanged
+            ) {
+                prefixData.prev = "";
+                return
+            }
+
             // Debounce/Prevent duplicate mouse events if needed
             if (prefixData.prev === event.type && ["mouseover", "mouseout"].includes(event.type)) {
                 return;
             }
             prefixData.prev = event.type;
+            if (target.type === "checkbox" || target.type === "radio")
+                prefixData.checked = target.checked;
 
             // Check for 'actions' blocking
             const actionsAttr = target.attributes.getNamedItem("actions")?.value || "";
@@ -263,6 +313,11 @@ const CoCreateEvents = {
         }
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     _initObserver: function (el, prefix) {
         // Updated to dash: prefix-selector, prefix-query, prefix-attribute-filter, prefix-types
         let selector = el.getAttribute(`${prefix}-selector`) || el.getAttribute(`${prefix}-query`) || "";
@@ -298,6 +353,11 @@ const CoCreateEvents = {
         }
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     _initResizeObserver: function (el, prefix) {
         const resizeObserver = new ResizeObserver((entries) => {
             const lastEntry = entries[entries.length - 1];
@@ -311,6 +371,11 @@ const CoCreateEvents = {
         resizeObserver.observe(el);
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     _initIntersectionObserver: function (el, prefix) {
         // Updated to dash
         const rootSelector = el.getAttribute(`${prefix}-root`);
@@ -352,6 +417,11 @@ const CoCreateEvents = {
         intersectionObserver.observe(el);
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     __updateElements: async function (rootElement, prefix, events, params) {
         if (!rootElement.isConnected) return;
 
@@ -473,6 +543,11 @@ const CoCreateEvents = {
         );
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     setValue: async function (rootElement, sourceElement, targetElement, prefix, events) {
         // Handle Mouseout toggle logic
         if (events && events.includes("mouseout")) {
@@ -490,8 +565,40 @@ const CoCreateEvents = {
 
         const deactivate = (rootElement !== sourceElement);
 
-        // Iterate Attributes
+        // Expand the prefix object in place, preserving attribute order.
+        const attributes = [];
         for (const attribute of sourceElement.attributes) {
+            if (attribute.name === prefix) {
+                const rawValue = attribute.value?.trim();
+                let assignments = null;
+                let assignmentsFromAst = false;
+
+                // An empty prefix remains an initialization marker.
+                if (!rawValue) continue;
+                if (rawValue?.startsWith("$")) {
+                    assignments = await sourceElement.getAttributeAsync(attribute.name);
+                    assignmentsFromAst = true;
+                } else if (rawValue.startsWith("{")) {
+                    assignments = JSON.parse(rawValue);
+                } else {
+                    continue;
+                }
+                if (!assignments || typeof assignments !== 'object') continue;
+
+                for (const [name, value] of Object.entries(assignments)) {
+                    attributes.push({
+                        name: `${prefix}.${name}`,
+                        value,
+                        fromObject: !assignmentsFromAst
+                    });
+                }
+            } else {
+                attributes.push(attribute);
+            }
+        }
+
+        // Execute both forms through the existing assignment handlers.
+        for (const attribute of attributes) {
             const name = attribute.name;
 
             // Optimization: Skip if shorter than prefix + dot + min char
@@ -501,39 +608,27 @@ const CoCreateEvents = {
             // All options use Dash, so they will be ignored here.
             if (!name.startsWith(prefix) || name[prefix.length] !== '.') continue;
 
-            // Extract target name (e.g., 'value', 'style', 'src', 'data-something')
-            let targetName = name.substring(prefix.length + 1);
-            const explicitMethod = targetName.startsWith("$");
+            // Extract target name (e.g., 'value', 'style', 'src', 'data-something')
+            let targetName = name.substring(prefix.length + 1);
+            const explicitProperty = targetName.startsWith("$");
 
             let values = [];
-            let value = attribute.value;
-            if (value.startsWith("(") && value.endsWith(")")) {
-                let depth = 0;
-                let start = 0;
-                for (let i = 0; i < value.length; i++) {
-                    const char = value.charCodeAt(i);
-                    if (char === 40) {
-                        depth++;
-                    } else if (char === 41) {
-                        depth--;
-                    } else if (char === 44 && depth === 0) {
-                        values.push(value.slice(start, i).trim().slice(1, -1));
-                        start = i + 1;
-                    }
-                }
-                values.push(value.slice(start).trim().slice(1, -1));
+            const value = attribute.fromObject
+                ? await astAsync({
+                    executeAST: attribute.value,
+                    node: sourceElement,
+                    sandbox: { $this: sourceElement }
+                })
+                : sourceElement.getAttribute(name);
+            // Parse CSV for rotation
+            if (typeof value === 'string') {
+                values = value.split(',').map(v => v.trim());
+            } else if (Array.isArray(value)) {
+                values = value;
             } else {
-                value = sourceElement.getAttribute(name);
-                // Parse CSV for rotation
-                if (typeof value === 'string') {
-                    values = value.split(',').map(v => v.trim());
-                } else if (Array.isArray(value)) {
-                    values = value;
-                } else {
-                    values = [value];
-                }
+                values = [value];
             }
-            // getAttribute has AST built in and resolves a wide range of operators.
+            // Object values and dotted attribute values resolve through AST.
 
             let oldValue = "";
             let newValue = "";
@@ -589,28 +684,62 @@ const CoCreateEvents = {
                     }
                     break;
 
-                case 'insertadjacenthtml':
-                case 'insertadjacenttext':
-                case 'insertAdjacentHTML':
-                case 'insertAdjacentText':
-                    const position = sourceElement.getAttribute(name);;
-                    if (!position) continue;
+                case 'insertadjacenthtml':
+                case 'insertadjacenttext':
+                case 'insertAdjacentHTML':
+                case 'insertAdjacentText':
+                    if (!value) continue;
+                    const position = String(value).toLowerCase();
 
                     let content = "";
-                    if (sourceElement.getValue) {
-                        content = await sourceElement.getValue();
+                    if (sourceElement.hasAttribute(`${prefix}-value`)) {
+                        content = sourceElement.getAttribute(`${prefix}-value`);
+                    } else {
+                        const contentSelector = sourceElement.attributes
+                            .getNamedItem(`${prefix}-element`)?.value;
+                        let contentSource = sourceElement;
+                        if (contentSelector !== undefined) {
+                            [contentSource] = queryElements({
+                                element: sourceElement,
+                                prefix,
+                                selector: contentSelector
+                            });
+                            if (!contentSource) continue;
+                        }
+                        if (contentSource.getValue) content = contentSource.getValue();
                     }
-
-                    // Check for CoCreate Rich Text integration
-                    let domTextEditor = targetElement.parentElement?.closest("[contenteditable]");
-
-                    if (domTextEditor && typeof CoCreate !== 'undefined' && CoCreate.text) {
-                        CoCreate.text.insertAdjacentElement({
-                            domTextEditor,
-                            position,
-                            target: targetElement,
-                            elementValue: content
-                        });
+                    if (content && typeof content.then === 'function') {
+                        content = await content;
+                    }
+                    content ??= "";
+
+                    // Resolve adjacency to canonical source coordinates for editors.
+                    const currentEditor = targetElement.editor;
+                    const editorDetails = typeof currentEditor?.getStart === "function"
+                        ? currentEditor : targetElement.editorDetails;
+                    const editorElement = editorDetails?.element || editorDetails?.editorElement;
+                    if (editorElement?.editor?.updateText) {
+                        const point = editorDetails.getInsertionPoint?.(position);
+                        if (point) {
+                            await point.editor.updateText({ start: point.offset, length: 0, value: String(content) });
+                            break;
+                        }
+                        if (typeof editorDetails.getInsertionPoint === "function")
+                            throw new RangeError("Editor insertion position is not valid for this element.");
+                        const outerRange = editorDetails.getOuterRange?.();
+                        const contentRange = editorDetails.getContentRange?.();
+                        const legacyBoundary = {
+                            beforebegin: "start", afterbegin: "contentStart",
+                            beforeend: "contentEnd", afterend: "end"
+                        }[position];
+                        const start = position === "beforebegin" ? outerRange?.start ?? editorDetails.start
+                            : position === "afterbegin" ? contentRange?.start ?? editorDetails.contentStart
+                                : position === "beforeend" ? contentRange?.end ?? editorDetails.contentEnd
+                                    : position === "afterend" ? outerRange?.end ?? editorDetails.end
+                                        : undefined;
+                        if (!legacyBoundary || !Number.isInteger(start))
+                            throw new RangeError("Editor insertion requires a current source range for the target.");
+                        await editorElement.editor.updateText({ start, length: 0, value: String(content) });
                     } else {
                         const isHtml = targetName.toLowerCase().includes('html');
                         if (isHtml) {
@@ -618,34 +747,34 @@ const CoCreateEvents = {
                         } else {
                             targetElement.insertAdjacentText(position, content);
                         }
-                    }
-                    break;
-
-                case 'insertadjacentelement':
-                case 'insertAdjacentElement':
-                    const elementPosition = sourceElement.getAttribute(name);
-                    const elementSelector =
-                        sourceElement.attributes.getNamedItem(`${prefix}-element`)?.value;
-                    if (!elementPosition || !elementSelector) continue;
-
-                    const elementsToInsert = queryElements({
-                        element: sourceElement,
-                        prefix,
-                        selector: elementSelector
-                    });
-                    const elementToInsert = elementsToInsert[0];
-                    if (
-                        elementToInsert &&
-                        typeof targetElement.insertAdjacentElement === 'function'
-                    ) {
-                        targetElement.insertAdjacentElement(
-                            elementPosition,
-                            elementToInsert
-                        );
-                    }
-                    break;
-
-                case 'value':
+                    }
+                    break;
+
+                case 'insertadjacentelement':
+                case 'insertAdjacentElement':
+                    const elementPosition = value;
+                    const elementSelector =
+                        sourceElement.attributes.getNamedItem(`${prefix}-element`)?.value;
+                    if (!elementPosition || !elementSelector) continue;
+
+                    const elementsToInsert = queryElements({
+                        element: sourceElement,
+                        prefix,
+                        selector: elementSelector
+                    });
+                    const elementToInsert = elementsToInsert[0];
+                    if (
+                        elementToInsert &&
+                        typeof targetElement.insertAdjacentElement === 'function'
+                    ) {
+                        targetElement.insertAdjacentElement(
+                            elementPosition,
+                            elementToInsert
+                        );
+                    }
+                    break;
+
+                case 'value':
                     if (targetElement.getValue) {
                         oldValue = await targetElement.getValue();
                     } else {
@@ -656,7 +785,14 @@ const CoCreateEvents = {
                     newValue = this.__getNextValue(values, oldValue, deactivate);
 
                     if (targetElement.setValue) {
-                        targetElement.setValue(newValue);
+                        if (
+                            targetElement === sourceElement &&
+                            ["input", "change"].includes(prefix)
+                        ) {
+                            targetElement.setValue(newValue, true);
+                        } else {
+                            targetElement.setValue(newValue);
+                        }
                     } else {
                         targetElement.value = newValue;
                     }
@@ -665,27 +801,46 @@ const CoCreateEvents = {
                 default:
                     // Generic handling: Try Property first, then Attribute
 
-                    // 1. Try Property
-                    if (targetElement[targetName] !== undefined || explicitMethod) {
-                        if (explicitMethod)
-                            targetName = targetName.substring(1)
-                        oldValue = targetElement[targetName];
+                    // $ always selects a property, including one not yet defined.
+                    let propertyName;
+                    let propertyTarget = targetElement;
+                    let propertyValue;
+                    if (explicitProperty || (
+                        propertyName = resolveProperty(targetElement, targetName)
+                    ) !== undefined) {
+                        if (explicitProperty) {
+                            const propertyPath = resolvePropertyPath(
+                                targetElement,
+                                targetName.substring(1)
+                            );
+                            if (propertyPath) {
+                                propertyTarget = propertyPath.target;
+                                propertyName = propertyPath.key;
+                                propertyValue = propertyPath.value;
+                            } else {
+                                targetName = targetName.substring(1);
+                                propertyName = resolveProperty(targetElement, targetName);
+                            }
+                        }
+                        targetName = propertyName ?? targetName;
+                        propertyValue ??= propertyTarget[targetName];
+                        oldValue = propertyValue;
                         if (!values.includes(oldValue) && typeof oldValue !== 'function') oldValue = "";
 
-                        newValue = this.__getNextValue(values, oldValue, deactivate);
-
-                        if (typeof targetElement[targetName] === 'function') {
-                            // A non-$ method binding with value=false disables
-                            // the action. Explicit $method bindings may still
-                            // intentionally pass false as an argument.
-                            if (
-                                explicitMethod ||
-                                (newValue !== false && newValue !== "false")
-                            ) {
-                                targetElement[targetName](newValue);
-                            }
-                        } else {
-                            targetElement[targetName] = newValue;
+                        newValue = this.__getNextValue(values, oldValue, deactivate);
+
+                        if (typeof propertyValue === 'function') {
+                            // A non-$ method binding with value=false disables
+                            // the action. Explicit $ bindings may still
+                            // intentionally pass false as an argument.
+                            if (
+                                explicitProperty ||
+                                (newValue !== false && newValue !== "false")
+                            ) {
+                                propertyValue.call(propertyTarget, newValue);
+                            }
+                        } else {
+                            propertyTarget[targetName] = newValue;
                         }
                     }
                     // 2. Fallback to Attribute
@@ -703,6 +858,11 @@ const CoCreateEvents = {
         }
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     __getNextValue: function (values, val, deactivate) {
         if (deactivate) return "";
         const size = values.length;
@@ -718,3 +878,49 @@ const CoCreateEvents = {
 CoCreateEvents.init();
 
 export default CoCreateEvents;
+
+/**
+ *
+ * @name event-name
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name style
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name type
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ * A simple events component in vanilla javascript. Easily configured using HTML5 attributes and/or JavaScript API.
+ *
+ * @module events
+ * @environment client
+ */
+
+/**
+ * Declarative selectors recognized by this module.
+ *
+ * @name declarative-selectors
+ * @kind member
+ * @selectors
+ * @environment client
+ * @example
+ * ```json
+ * [
+ *   "[event-name]"
+ * ]
+ * ```
+ */