@cocreate/events 1.34.0 → 2.0.0

package/src/index.js

@@ -18,17 +18,58 @@
 // 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(),
 
+    // Known targets initialize for every prefix without an additional marker.
+    // Arbitrary prefix.* properties and methods still opt in through
+    // [prefix], [prefix-group], or [prefix-query].
+    knownTargets: [
+        "class",
+        "src",
+        "href",
+        "value",
+        "hidden",
+        "disabled",
+        "checked",
+        "selected",
+        "aria-expanded",
+        "aria-hidden",
+        "aria-pressed",
+        "aria-current",
+        "textContent",
+        "innerHTML",
+        "save"
+    ],
+
+    /**
+     *
+ * @public
+ * @environment client
+ */
     init: function (prefix, events) {
         if (prefix && events) {
             this.initPrefix(prefix, events);
@@ -48,7 +89,8 @@ const CoCreateEvents = {
                 "resize": ["onload", "resize"],
                 "localstorage": ["onload"],
                 "focus": ["focus"],
-                "blur": ["blur"]
+                "blur": ["blur"],
+                "error": ["error"]
             };
 
             for (const [p, e] of Object.entries(defaults)) {
@@ -59,11 +101,11 @@ const CoCreateEvents = {
         // Initialize from existing elements with [event-name]
         const customEventEls = document.querySelectorAll("[event-name]");
         const processedNames = new Set();
-        
+
         for (const customEventEl of customEventEls) {
             let names = customEventEl.getAttribute("event-name");
             if (!names) continue;
-            
+
             names.split(",").forEach(name => {
                 name = name.trim();
                 if (name && !processedNames.has(name)) {
@@ -89,6 +131,11 @@ const CoCreateEvents = {
         });
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     initPrefix: function (prefix, events) {
         action.init({
             name: prefix,
@@ -105,7 +152,14 @@ const CoCreateEvents = {
         });
 
         // Updated selector to use dash for options: prefix-group, prefix-query
-        const selector = `[${prefix}], [${prefix}-group], [${prefix}-query]`;
+        const knownTargets = this.knownTargets.map(target => `[${prefix}\\.${target}]`);
+        const selector = [
+            `[${prefix}]`,
+            `[${prefix}-group]`,
+            `[${prefix}-query]`,
+            `[${prefix}-element]`,
+            ...knownTargets
+        ].join(", ");
 
         observer.init({
             name: "CoCreateEventAttributes",
@@ -122,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;
@@ -206,14 +270,29 @@ 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.getAttribute("actions") || "";
+            const actionsAttr = target.attributes.getNamedItem("actions")?.value || "";
             if (actionsAttr.includes(prefix)) return;
 
             // Handle lifecycle controls (using dash)
@@ -222,7 +301,7 @@ const CoCreateEvents = {
                 { attr: "stop-propagation", method: "stopPropagation" },
                 { attr: "stop-immediate-propagation", method: "stopImmediatePropagation" }
             ];
-            
+
             for (const { attr, method } of lifecycleAttributes) {
                 const attrValue = target.getAttribute(`${prefix}-${attr}`);
                 if (attrValue !== null && attrValue !== "false") {
@@ -234,13 +313,18 @@ 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`) || "";
         let attributeFilter = (el.getAttribute(`${prefix}-attribute-filter`) || "")
             .split(/\s*,\s*/)
             .filter(item => item);
-        
+
         let types = (el.getAttribute(`${prefix}-types`) || "")
             .split(/\s*,\s*/)
             .filter(item => item);
@@ -269,17 +353,29 @@ const CoCreateEvents = {
         }
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     _initResizeObserver: function (el, prefix) {
         const resizeObserver = new ResizeObserver((entries) => {
             const lastEntry = entries[entries.length - 1];
             const { width } = lastEntry.contentRect;
-            // Keeps dash style for this status attribute
-            el.setAttribute(`${prefix}-if-value`, width + "px");
+            const widthValue = width + "px";
+            el.width = widthValue;
+            // Keeps dash style for conditional resize bindings.
+            el.setAttribute(`${prefix}-if-value`, widthValue);
             this.__updateElements(el, prefix);
         });
         resizeObserver.observe(el);
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     _initIntersectionObserver: function (el, prefix) {
         // Updated to dash
         const rootSelector = el.getAttribute(`${prefix}-root`);
@@ -289,8 +385,8 @@ const CoCreateEvents = {
         const trigger = el.getAttribute(`${prefix}-trigger`) || "both";
 
         const root = rootSelector ? document.querySelector(rootSelector) : null;
-        const validThreshold = Array.isArray(threshold) 
-            ? threshold.filter(v => v >= 0 && v <= 1) 
+        const validThreshold = Array.isArray(threshold)
+            ? threshold.filter(v => v >= 0 && v <= 1)
             : [0];
 
         const once = el.getAttribute(`${prefix}-once`);
@@ -321,20 +417,25 @@ const CoCreateEvents = {
         intersectionObserver.observe(el);
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     __updateElements: async function (rootElement, prefix, events, params) {
         if (!rootElement.isConnected) return;
 
         // 1. Determine targets based on prefix-group
         let sourceElements = [rootElement];
         const sourceGroup = rootElement.getAttribute(`${prefix}-group`);
-        
+
         if (sourceGroup) {
             sourceElements = document.querySelectorAll(`[${prefix}-group="${sourceGroup}"]`);
         }
 
         // 2. Iterate through sourceElements
         for (const sourceElement of sourceElements) {
-            
+
             // --- Global Options (Dash) ---
 
             // onEvent
@@ -353,18 +454,18 @@ const CoCreateEvents = {
             const intervalAttr = sourceElement.getAttribute(`${prefix}-set-interval`);
             if (intervalAttr !== null) {
                 const intervalMs = parseInt(intervalAttr, 10) || 0;
-                
+
                 if (!sourceElement.eventsInterval) {
                     sourceElement.eventsInterval = {};
                 }
-                
+
                 const currentInterval = sourceElement.eventsInterval[prefix];
 
                 if (intervalMs > 0) {
                     // Start or update interval
                     if (!currentInterval || currentInterval.delay !== intervalMs) {
                         if (currentInterval) clearInterval(currentInterval.id);
-                        
+
                         sourceElement.eventsInterval[prefix] = {
                             delay: intervalMs,
                             id: setInterval(() => {
@@ -401,7 +502,7 @@ const CoCreateEvents = {
 
             // once
             const onceAttr = sourceElement.getAttribute(`${prefix}-once`);
-            if (onceAttr !== null) { 
+            if (onceAttr !== null) {
                 if (!sourceElement.eventsOnce) {
                     sourceElement.eventsOnce = [prefix];
                 } else if (sourceElement.eventsOnce.includes(prefix)) {
@@ -412,7 +513,9 @@ const CoCreateEvents = {
             }
 
             // --- Resolve Targets ---
-            const querySelector = sourceElement.getAttribute(`${prefix}-query`);
+            // const querySelector = sourceElement.getAttribute(`${prefix}-query`);
+            const querySelector =
+                sourceElement.attributes[`${prefix}-query`]?.value;
             let targetElements = [sourceElement];
 
             if (querySelector || params) {
@@ -440,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")) {
@@ -457,28 +565,62 @@ 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
             if (name.length <= prefix.length + 1) continue;
-            
+
             // STRICT RULE: Only process attributes with DOT separator.
             // 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')
-            const targetName = name.substring(prefix.length + 1);
-
-            // Get Value
-            let value = sourceElement.getAttribute(name);
-            if (value === "$value" && sourceElement.getValue) {
-                value = await sourceElement.getValue();
-            } 
+            let targetName = name.substring(prefix.length + 1);
+            const explicitProperty = targetName.startsWith("$");
 
-            // Parse CSV for rotation
             let values = [];
+            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)) {
@@ -486,18 +628,25 @@ const CoCreateEvents = {
             } else {
                 values = [value];
             }
+            // Object values and dotted attribute values resolve through AST.
 
             let oldValue = "";
             let newValue = "";
 
             switch (targetName) {
+                case 'type':
+                    oldValue = targetElement.getAttribute('type') || '';
+                    newValue = this.__getNextValue(values, oldValue, deactivate);
+                    targetElement.setAttribute('type', newValue);
+                    break;
+
                 case 'style':
                     if (targetElement.getAttribute("style")) {
                         // Normalize style string for comparison
                         const styles = targetElement.getAttribute("style")
                             .split(";")
                             .map(x => x.trim().replace(/\s/g, ""));
-                        
+
                         oldValue = values.find(x => styles.includes(x.replace(/\s/g, ""))) || "";
                     }
                     newValue = this.__getNextValue(values, oldValue, deactivate);
@@ -527,7 +676,7 @@ const CoCreateEvents = {
 
                     if (oldValue) {
                         oldValue.split(" ").forEach(c => targetElement.classList.remove(c));
-                        if (values.length === 1 && !newValue) return; 
+                        if (values.length === 1 && !newValue) return;
                     }
 
                     if (newValue) {
@@ -537,26 +686,60 @@ const CoCreateEvents = {
 
                 case 'insertadjacenthtml':
                 case 'insertadjacenttext':
-                case 'insertAdjacentHTML': 
+                case 'insertAdjacentHTML':
                 case 'insertAdjacentText':
-                    const position = sourceElement.getAttribute(name);; 
-                    if (!position) continue;
+                    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) {
@@ -567,6 +750,30 @@ const CoCreateEvents = {
                     }
                     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();
@@ -578,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;
                     }
@@ -586,25 +800,54 @@ const CoCreateEvents = {
 
                 default:
                     // Generic handling: Try Property first, then Attribute
-                    
-                    // 1. Try Property
-                    if (targetElement[targetName] !== undefined) {
-                        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') {
-                            targetElement[targetName](newValue);
+                        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 {
-                            targetElement[targetName] = newValue;
+                            propertyTarget[targetName] = newValue;
                         }
-                    } 
+                    }
                     // 2. Fallback to Attribute
                     else {
                         oldValue = targetElement.getAttribute(targetName);
                         if (!values.includes(oldValue)) oldValue = "";
-                        
+
                         newValue = this.__getNextValue(values, oldValue, deactivate);
 
                         // Handle Namespaced Attributes (e.g. svg:href) if encoded in name
@@ -615,6 +858,11 @@ const CoCreateEvents = {
         }
     },
 
+    /**
+     *
+ * @public
+ * @environment client
+ */
     __getNextValue: function (values, val, deactivate) {
         if (deactivate) return "";
         const size = values.length;
@@ -629,4 +877,50 @@ const CoCreateEvents = {
 
 CoCreateEvents.init();
 
-export default CoCreateEvents;
+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]"
+ * ]
+ * ```
+ */