feat: Add unified callback API for easier Phoenix integration

.gitignore

@@ -55,6 +55,7 @@ Thumbs.db
 packages/phoenix-ng/projects/phoenix-app/cypress/videos
 packages/phoenix-ng/projects/phoenix-app/cypress/screenshots
 packages/phoenix-ng/projects/phoenix-app/cypress/downloads
+packages/phoenix-event-display/documentation/js/routes/routes_index.js
 
 # Added as per https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
 .pnp.*

packages/phoenix-event-display/src/event-display.ts

@@ -39,6 +39,19 @@ export class EventDisplay {
   private onEventsChange: ((events: any) => void)[] = [];
   /** Array containing callbacks to be called when the displayed event changes. */
   private onDisplayedEventChange: ((nowDisplayingEvent: any) => void)[] = [];
+  /** Array containing callbacks to be called when an object is selected. */
+  private onObjectSelectedCallbacks: ((object: any, data: any) => void)[] = [];
+  /** Array containing callbacks to be called when an object is deselected. */
+  private onObjectDeselectedCallbacks: ((object: any) => void)[] = [];
+  /** Array containing callbacks to be called when an object is hovered. */
+  private onObjectHoveredCallbacks: ((object: any, data: any) => void)[] = [];
+  /** Array containing callbacks to be called when object hover ends. */
+  private onObjectHoverEndCallbacks: ((object: any) => void)[] = [];
+  /** Array containing callbacks to be called when selection state changes. */
+  private onSelectionChangedCallbacks: ((
+    selectedObjects: any[],
+    selectionData: any,
+  ) => void)[] = [];
   /** Three manager for three.js operations. */
   private graphicsLibrary: ThreeManager;
   /** Info logger for storing event display logs. */
@@ -83,6 +96,10 @@ export class EventDisplay {
     this.graphicsLibrary.init(configuration);
     // Initialize the UI with configuration
     this.ui.init(configuration);
+
+    // Set up selection callbacks for external integrations
+    this.setupSelectionCallbacks();
+
     // Set up for the state manager
     this.getStateManager().setEventDisplay(this);
 
@@ -117,6 +134,11 @@ export class EventDisplay {
     // Clear accumulated callbacks
     this.onEventsChange = [];
     this.onDisplayedEventChange = [];
+    this.onObjectSelectedCallbacks = [];
+    this.onObjectDeselectedCallbacks = [];
+    this.onObjectHoveredCallbacks = [];
+    this.onObjectHoverEndCallbacks = [];
+    this.onSelectionChangedCallbacks = [];
     // Reset singletons for clean view transition
     this.loadingManager?.reset();
     this.stateManager?.resetForViewTransition();
@@ -610,6 +632,158 @@ export class EventDisplay {
     };
   }
 
+  /**
+   * Add a callback to be invoked when an object is selected.
+   * @param callback Callback receiving the selected object and associated data.
+   * @returns Unsubscribe function to remove the callback.
+   */
+  public onObjectSelected(
+    callback: (object: any, data?: any) => void,
+  ): () => void {
+    this.onObjectSelectedCallbacks.push(callback);
+    return () => {
+      const index = this.onObjectSelectedCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.onObjectSelectedCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Add a callback to be invoked when an object is deselected.
+   * @param callback Callback receiving the deselected object.
+   * @returns Unsubscribe function to remove the callback.
+   */
+  public onObjectDeselected(callback: (object: any) => void): () => void {
+    this.onObjectDeselectedCallbacks.push(callback);
+    return () => {
+      const index = this.onObjectDeselectedCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.onObjectDeselectedCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Add a callback to be invoked when an object is hovered.
+   * @param callback Callback receiving the hovered object and associated data.
+   * @returns Unsubscribe function to remove the callback.
+   */
+  public onObjectHovered(
+    callback: (object: any, data?: any) => void,
+  ): () => void {
+    this.onObjectHoveredCallbacks.push(callback);
+    return () => {
+      const index = this.onObjectHoveredCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.onObjectHoveredCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Add a callback to be invoked when object hover ends.
+   * @param callback Callback receiving the object that was hovered.
+   * @returns Unsubscribe function to remove the callback.
+   */
+  public onObjectHoverEnd(callback: (object: any) => void): () => void {
+    this.onObjectHoverEndCallbacks.push(callback);
+    return () => {
+      const index = this.onObjectHoverEndCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.onObjectHoverEndCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Add a callback to be invoked when the selection state changes.
+   * @param callback Callback receiving the list of selected objects and selection data.
+   * @returns Unsubscribe function to remove the callback.
+   */
+  public onSelectionChanged(
+    callback: (selectedObjects: any[], selectionData?: any) => void,
+  ): () => void {
+    this.onSelectionChangedCallbacks.push(callback);
+    return () => {
+      const index = this.onSelectionChangedCallbacks.indexOf(callback);
+      if (index > -1) {
+        this.onSelectionChangedCallbacks.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Internal method to fire object selected callbacks.
+   * Called by the SelectionManager when an object is selected.
+   * @internal
+   */
+  private fireObjectSelectedCallback(object: any, data?: any) {
+    this.onObjectSelectedCallbacks.forEach((callback) =>
+      callback(object, data),
+    );
+  }
+
+  /**
+   * Internal method to fire object deselected callbacks.
+   * Called by the SelectionManager when an object is deselected.
+   * @internal
+   */
+  private fireObjectDeselectedCallback(object: any, data?: any) {
+    this.onObjectDeselectedCallbacks.forEach((callback) => callback(object));
+  }
+
+  /**
+   * Internal method to fire object hovered callbacks.
+   * Called by the SelectionManager when an object is hovered.
+   * @internal
+   */
+  private fireObjectHoveredCallback(object: any, data?: any) {
+    this.onObjectHoveredCallbacks.forEach((callback) => callback(object, data));
+  }
+
+  /**
+   * Internal method to fire object hover end callbacks.
+   * Called by the SelectionManager when hover ends.
+   * @internal
+   */
+  private fireObjectHoverEndCallback(object: any, data?: any) {
+    this.onObjectHoverEndCallbacks.forEach((callback) => callback(object));
+  }
+
+  /**
+   * Internal method to fire selection changed callbacks.
+   * Called by the SelectionManager when selection state changes.
+   * @internal
+   */
+  private fireSelectionChangedCallback(
+    selectedObjects: any[],
+    selectionData?: any,
+  ) {
+    this.onSelectionChangedCallbacks.forEach((callback) =>
+      callback(selectedObjects, selectionData),
+    );
+  }
+
+  /**
+   * Set up selection callbacks on ThreeManager's SelectionManager.
+   * This connects the internal fire*Callback methods to the SelectionManager.
+   * @private
+   */
+  private setupSelectionCallbacks(): void {
+    this.graphicsLibrary.setSelectionCallbacks(
+      (object: any, data?: any) =>
+        this.fireObjectSelectedCallback(object, data),
+      (object: any, data?: any) =>
+        this.fireObjectDeselectedCallback(object, data),
+      (object: any, data?: any) => this.fireObjectHoveredCallback(object, data),
+      (object: any, data?: any) =>
+        this.fireObjectHoverEndCallback(object, data),
+      (selectedObjects: any[], data?: any) =>
+        this.fireSelectionChangedCallback(selectedObjects, data),
+    );
+  }
+
   /**
    * Get metadata associated to the displayed event (experiment info, time, run, event...).
    * @returns Metadata of the displayed event.

packages/phoenix-event-display/src/managers/three-manager/index.ts

@@ -1192,6 +1192,53 @@ export class ThreeManager {
     return this.selectionManager;
   }
 
+  /**
+   * Set selection callbacks on the SelectionManager for EventDisplay integration.
+   * @param onObjectSelectedCallback Called when an object is selected
+   * @param onObjectDeselectedCallback Called when an object is deselected
+   * @param onObjectHoveredCallback Called when an object is hovered
+   * @param onObjectHoverEndCallback Called when hover ends
+   * @param onSelectionChangedCallback Called when selection changes
+   * @internal Used by EventDisplay to integrate selection callbacks
+   */
+  public setSelectionCallbacks(
+    onObjectSelectedCallback?: ((object: any, data?: any) => void) | null,
+    onObjectDeselectedCallback?: ((object: any) => void) | null,
+    onObjectHoveredCallback?: ((object: any, data?: any) => void) | null,
+    onObjectHoverEndCallback?: ((object: any) => void) | null,
+    onSelectionChangedCallback?:
+      | ((selectedObjects: any[], selectionData?: any) => void)
+      | null,
+  ): void {
+    const selectionManager = this.getSelectionManager();
+
+    if (onObjectSelectedCallback !== undefined) {
+      selectionManager.setOnObjectSelectedCallback(onObjectSelectedCallback);
+    }
+    if (onObjectDeselectedCallback !== undefined) {
+      selectionManager.setOnObjectDeselectedCallback(
+        onObjectDeselectedCallback,
+      );
+    }
+    if (onObjectHoveredCallback !== undefined) {
+      selectionManager.setOnObjectHoveredCallback(onObjectHoveredCallback);
+    }
+    if (onObjectHoverEndCallback !== undefined) {
+      selectionManager.setOnObjectHoverEndCallback(onObjectHoverEndCallback);
+    }
+    if (onSelectionChangedCallback !== undefined) {
+      selectionManager.setOnSelectionChangedCallback(
+        onSelectionChangedCallback
+          ? (set, arr) =>
+              onSelectionChangedCallback(arr, {
+                selectionSet: set,
+                selectionArray: arr,
+              })
+          : null,
+      );
+    }
+  }
+
   /**
    * Animates camera position.
    * @param cameraPosition End position.