@jay-framework/runtime-automation 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -4,27 +4,43 @@ import { TrackByMap } from '@jay-framework/view-state-merge';
 
 /**
  * Coordinate path identifying an element.
+ * For simple elements: ['refName']
  * For forEach items: ['trackByValue', 'refName']
- * For nested: ['parentTrackBy', 'childTrackBy', 'refName']
+ * For nested forEach: ['parentTrackBy', 'childTrackBy', 'refName']
  */
 type Coordinate = string[];
 /**
- * Represents an interactive element on the page.
+ * A single interactive element instance — has the DOM element and its coordinate.
+ */
+interface InteractionInstance {
+    /** Full coordinate path identifying this element */
+    coordinate: Coordinate;
+    /** The actual DOM element — can be used to read/set values or call click() */
+    element: HTMLElement;
+    /** Relevant events this element handles (e.g., ["click"] or ["input", "change"]) */
+    events: string[];
+}
+/**
+ * Interactions grouped by refName.
+ * Each ref has one or more instances (multiple when inside a forEach).
  */
 interface Interaction {
     /** Ref name from jay-html */
     refName: string;
-    /** Full coordinate path (for forEach items) */
+    /** All instances of this ref (one per forEach item, or a single entry for non-forEach) */
+    items: InteractionInstance[];
+    /** Human-readable description (from contract if available) */
+    description?: string;
+}
+/**
+ * Internal: raw per-element data from the interaction collector.
+ * Not part of the public API — consumed by the grouping function.
+ */
+interface CollectedInteraction {
+    refName: string;
     coordinate: Coordinate;
-    /** The actual DOM element - can be used to read/set values or call click() */
     element: HTMLElement;
-    /** HTML element type (e.g., "HTMLButtonElement") */
-    elementType: string;
-    /** Events this element can handle (e.g., ["click", "input"]) */
     supportedEvents: string[];
-    /** For collection items: the item's ViewState */
-    itemContext?: object;
-    /** Human-readable description (from contract if available) */
     description?: string;
 }
 /**
@@ -33,7 +49,7 @@ interface Interaction {
 interface PageState {
     /** Current ViewState of the component (includes headless component data under their keys) */
     viewState: object;
-    /** All available interactions with their DOM elements */
+    /** Available interactions grouped by ref name */
     interactions: Interaction[];
     /** Custom events the component can emit */
     customEvents: Array<{
@@ -44,21 +60,21 @@ interface PageState {
  * Automation API attached to wrapped components.
  */
 interface AutomationAPI {
-    /** Get current page state and available interactions */
+    /** Get current page state and available interactions (grouped by ref) */
     getPageState(): PageState;
     /** Trigger an event on an element by coordinate */
     triggerEvent(eventType: string, coordinate: Coordinate, eventData?: object): void;
-    /** Subscribe to ViewState changes - called on every ViewState update */
+    /** Subscribe to ViewState changes — called on every ViewState update */
     onStateChange(callback: (state: PageState) => void): () => void;
-    /** Get a specific interaction by coordinate */
-    getInteraction(coordinate: Coordinate): Interaction | undefined;
+    /** Get a specific interaction instance by coordinate (returns the DOM element) */
+    getInteraction(coordinate: Coordinate): InteractionInstance | undefined;
     /** Get list of custom events the component emits */
     getCustomEvents(): Array<{
         name: string;
     }>;
     /** Subscribe to a custom component event (e.g., 'AddToCart') */
     onComponentEvent(eventName: string, callback: (eventData: any) => void): () => void;
-    /** Cleanup - call when component is unmounted */
+    /** Cleanup — call when component is unmounted */
     dispose(): void;
 }
 /** @deprecated Use Interaction instead */
@@ -132,6 +148,11 @@ declare const AUTOMATION_CONTEXT: _jay_framework_runtime.ContextMarker<Automatio
  * Collects all interactive elements from a component's refs.
  * Handles nested refs (e.g., headless components) by recursively traversing the refs tree.
  */
-declare function collectInteractions(refs: any): Interaction[];
+declare function collectInteractions(refs: any): CollectedInteraction[];
+
+/**
+ * Groups raw collected interactions by refName and filters events to relevant ones.
+ */
+declare function groupInteractions(raw: CollectedInteraction[]): Interaction[];
 
-export { type AIAgentAPI, type AIInteraction, type AIPageState, AUTOMATION_CONTEXT, type AutomationAPI, type AutomationAgentOptions, type AutomationWrappedComponent, type Coordinate, type Interaction, type PageState, collectInteractions, wrapWithAutomation };
+export { type AIAgentAPI, type AIInteraction, type AIPageState, AUTOMATION_CONTEXT, type AutomationAPI, type AutomationAgentOptions, type AutomationWrappedComponent, type Coordinate, type Interaction, type InteractionInstance, type PageState, collectInteractions, groupInteractions, wrapWithAutomation };

package/dist/index.js

@@ -91,14 +91,13 @@ function collectInteractionsRecursive(refs, interactions) {
       continue;
     if (refImpl.elements && refImpl.elements instanceof Set) {
       for (const elem of refImpl.elements) {
-        if (elem.element) {
+        if (elem.element && !isDisabled(elem.element)) {
           interactions.push({
             refName,
             coordinate: elem.coordinate || [refName],
             element: elem.element,
-            elementType: getElementType(elem.element),
             supportedEvents: getSupportedEvents(elem.element),
-            itemContext: elem.viewState
+            description: elem.description
           });
         }
       }
@@ -117,8 +116,12 @@ function isNestedRefsObject(obj) {
     return false;
   return true;
 }
-function getElementType(element) {
-  return element.constructor.name;
+function isDisabled(element) {
+  if ("disabled" in element && element.disabled) {
+    return true;
+  }
+  const fieldset = element.closest?.("fieldset:disabled");
+  return !!fieldset;
 }
 function getSupportedEvents(element) {
   const base = ["click", "focus", "blur"];
@@ -142,11 +145,45 @@ function getSupportedEvents(element) {
   }
   return base;
 }
+function groupInteractions(raw) {
+  const byRef = /* @__PURE__ */ new Map();
+  for (const item of raw) {
+    let group = byRef.get(item.refName);
+    if (!group) {
+      group = [];
+      byRef.set(item.refName, group);
+    }
+    group.push(item);
+  }
+  return Array.from(byRef.entries()).map(([refName, items]) => ({
+    refName,
+    description: items[0].description,
+    items: items.map(toInstance)
+  }));
+}
+function toInstance(raw) {
+  return {
+    coordinate: raw.coordinate,
+    element: raw.element,
+    events: relevantEvents(raw)
+  };
+}
+function relevantEvents(raw) {
+  const el = raw.element;
+  if (el instanceof HTMLButtonElement || el instanceof HTMLAnchorElement) {
+    return ["click"];
+  }
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+    return raw.supportedEvents.filter((e) => e === "input" || e === "change");
+  }
+  return raw.supportedEvents;
+}
 const VIEW_STATE_CHANGE = "viewStateChange";
 class AutomationAgent {
   constructor(component, options) {
     __publicField(this, "stateListeners", /* @__PURE__ */ new Set());
-    __publicField(this, "cachedInteractions", null);
+    __publicField(this, "cachedRaw", null);
+    __publicField(this, "cachedGrouped", null);
     __publicField(this, "viewStateHandler", null);
     /**
      * When slow rendering is used, this holds the merged slow+fast ViewState.
@@ -169,7 +206,8 @@ class AutomationAgent {
   }
   subscribeToUpdates() {
     this.viewStateHandler = () => {
-      this.cachedInteractions = null;
+      this.cachedRaw = null;
+      this.cachedGrouped = null;
       if (this.initialSlowViewState && this.trackByMap) {
         this.mergedViewState = deepMergeViewStates(
           this.initialSlowViewState,
@@ -187,33 +225,43 @@ class AutomationAgent {
     const state = this.getPageState();
     this.stateListeners.forEach((callback) => callback(state));
   }
-  getPageState() {
-    if (!this.cachedInteractions) {
-      this.cachedInteractions = collectInteractions(this.component.element?.refs);
+  getGrouped() {
+    if (!this.cachedGrouped) {
+      if (!this.cachedRaw) {
+        this.cachedRaw = collectInteractions(this.component.element?.refs);
+      }
+      this.cachedGrouped = groupInteractions(this.cachedRaw);
     }
+    return this.cachedGrouped;
+  }
+  getPageState() {
     return {
       // Use merged state if available (slow+fast), otherwise component's viewState
       viewState: this.mergedViewState || this.component.viewState,
-      interactions: this.cachedInteractions,
+      interactions: this.getGrouped(),
       customEvents: this.getCustomEvents()
     };
   }
   triggerEvent(eventType, coordinate, eventData) {
-    const interaction = this.getInteraction(coordinate);
-    if (!interaction) {
+    const instance = this.getInteraction(coordinate);
+    if (!instance) {
       throw new Error(`No element found at coordinate: ${coordinate.join("/")}`);
     }
     const event = new Event(eventType, { bubbles: true });
     if (eventData) {
       Object.assign(event, eventData);
     }
-    interaction.element.dispatchEvent(event);
+    instance.element.dispatchEvent(event);
   }
   getInteraction(coordinate) {
-    const state = this.getPageState();
-    return state.interactions.find(
-      (i) => i.coordinate.length === coordinate.length && i.coordinate.every((c, idx) => c === coordinate[idx])
-    );
+    for (const group of this.getGrouped()) {
+      for (const instance of group.items) {
+        if (instance.coordinate.length === coordinate.length && instance.coordinate.every((c, idx) => c === coordinate[idx])) {
+          return instance;
+        }
+      }
+    }
+    return void 0;
   }
   onStateChange(callback) {
     this.stateListeners.add(callback);
@@ -246,7 +294,8 @@ class AutomationAgent {
       this.viewStateHandler = null;
     }
     this.stateListeners.clear();
-    this.cachedInteractions = null;
+    this.cachedRaw = null;
+    this.cachedGrouped = null;
   }
 }
 function wrapWithAutomation(component, options) {
@@ -257,5 +306,6 @@ const AUTOMATION_CONTEXT = createJayContext();
 export {
   AUTOMATION_CONTEXT,
   collectInteractions,
+  groupInteractions,
   wrapWithAutomation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/runtime-automation",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Automation API for Jay components - enables programmatic state inspection and interaction triggering",
@@ -21,12 +21,12 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/runtime": "^0.11.0",
-    "@jay-framework/view-state-merge": "^0.11.0"
+    "@jay-framework/runtime": "^0.13.0",
+    "@jay-framework/view-state-merge": "^0.13.0"
   },
   "devDependencies": {
-    "@jay-framework/component": "^0.11.0",
-    "@jay-framework/dev-environment": "^0.11.0",
+    "@jay-framework/component": "^0.13.0",
+    "@jay-framework/dev-environment": "^0.13.0",
     "@types/node": "^20.11.5",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",