feat: Add unified callback API for easier Phoenix integration

[GaneshPatil7517]

Implements issue #826 by providing a unified, easy-to-use callback API that allows external applications to easily register callbacks on Phoenix actions without needing direct access to internal managers.

Changes Made

EventDisplay Class (src/event-display.ts)

• Added 5 new public methods for registering selection callbacks:

  • onObjectSelected(callback) - Called when an object is selected
  • onObjectDeselected(callback) - Called when an object is deselected
  • onObjectHovered(callback) - Called when an object is hovered
  • onObjectHoverEnd(callback) - Called when hover ends
  • onSelectionChanged(callback) - Called when selection changes

• All methods return unsubscribe functions for proper cleanup

• Added internal setupSelectionCallbacks() to wire up callbacks on init

• Added internal fire*Callback methods to dispatch events to registered listeners

SelectionManager Class (src/managers/three-manager/selection-manager.ts)

• Added callback properties for selection, hover, and deselection events
• Added setter methods: setOnObjectSelectedCallback(), setOnObjectDeselectedCallback(), etc.
• Integrated callback firing in selectObject() and deselectObject() methods
• Callbacks are triggered with relevant object and data information

ThreeManager Class (src/managers/three-manager/index.ts)

• Added setSelectionCallbacks() method to configure SelectionManager callbacks
• Acts as the bridge between EventDisplay and SelectionManager

Benefits

• Easy Integration: External apps can now easily register callbacks without understanding Phoenix's internal manager architecture
• Proper Cleanup: Unsubscribe functions ensure memory leaks don't occur
• Non-Intrusive: Existing functionality remains unchanged
• Use Case Support: Enables master classes, analysis applications, and other tools to react to user selections

Testing

• All existing tests pass
• No breaking changes to existing functionality
• Callbacks are properly wired through the manager chain

Example Usage

onst eventDisplay = new EventDisplay(config);

// Register callbacks
const unsubscribeSelect = eventDisplay.onObjectSelected((object, data) => {
  console.log('Selected:', object);
});

const unsubscribeChange = eventDisplay.onSelectionChanged((objects) => {
  console.log('Selection changed:', objects);
});

// Later, cleanup
unsubscribeSelect();
unsubscribeChange();

Fixes #826

[Copilot]

Pull request overview

Adds an external callback/subscription mechanism for object selection and hover events, wiring SelectionManager → ThreeManager → EventDisplay so external consumers can react to interaction changes.

Changes:

• Added configurable selection/hover callbacks to SelectionManager and invoked selection-related callbacks in programmatic select/deselect flows.
• Added a ThreeManager.setSelectionCallbacks bridge to attach callbacks onto SelectionManager.
• Added EventDisplay subscription APIs (onObjectSelected, onObjectDeselected, etc.) and wired them into ThreeManager during init.
• Added a new documentation/js/routes/routes_index.js file.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
packages/phoenix-event-display/src/managers/three-manager/selection-manager.ts	Introduces callback fields + setters and fires callbacks in selectObject/deselectObject.
packages/phoenix-event-display/src/managers/three-manager/index.ts	Adds setSelectionCallbacks wrapper to register callbacks on the SelectionManager.
packages/phoenix-event-display/src/event-display.ts	Adds subscription APIs and wires them into ThreeManager on init.
packages/phoenix-event-display/documentation/js/routes/routes_index.js	Adds a routes index file under documentation/.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

This PR enables previously skipped unit tests in the Angular packages and introduces a new selection/hover callback subscription API in phoenix-event-display intended for external integrations.

Changes:

• Unskips and updates several Jest tests in phoenix-ng to use more explicit mocks/spies.
• Adds selection/hover callback plumbing across SelectionManager, ThreeManager, and EventDisplay.
• Adds a documentation route index JS file under phoenix-event-display/documentation.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/phoenix-ng/projects/phoenix-ui-components/lib/services/file-loader.service.component.test.ts	Unskips and rewrites FileLoaderService test using instance spies instead of a standalone mock object.
packages/phoenix-ng/projects/phoenix-ui-components/lib/components/ui-menu/event-data-explorer/event-data-explorer-dialog/event-data-explorer-dialog.component.ts	Removes circular type import by introducing a local EventDataExplorerDialogData type.
packages/phoenix-ng/projects/phoenix-ui-components/lib/components/ui-menu/event-data-explorer/event-data-explorer-dialog/event-data-explorer-dialog.component.test.ts	Unskips dialog tests and injects FileLoaderService via a mock provider; improves eventDisplay mock.
packages/phoenix-ng/projects/phoenix-app/src/app/sections/cms/cms.component.test.ts	Unskips CMSComponent tests and mocks CMSLoader behavior via prototype spies.
packages/phoenix-event-display/src/managers/three-manager/selection-manager.ts	Adds callback registration + firing hooks for selection and hover state changes.
packages/phoenix-event-display/src/managers/three-manager/index.ts	Adds ThreeManager.setSelectionCallbacks to forward callbacks into SelectionManager.
packages/phoenix-event-display/src/event-display.ts	Adds public subscription APIs (onObjectSelected, etc.) and wires them to ThreeManager selection callbacks.
packages/phoenix-event-display/documentation/js/routes/routes_index.js	Adds a ROUTES_INDEX variable file under documentation routes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[GaneshPatil7517]

hey @sponce and @EdwardMoyse the pr is ready to review please review it when you get the time......

[sponce]

Thanks for this @GaneshPatil7517 ! I won't have time to do a deep review in the short term but this is already a nice base. Ideally, we should try to use this interface already, e.g. in the LHCb masterclass, to validate that it fulfills the needs. This will obviously take some time

[GaneshPatil7517]

Thanks for this @GaneshPatil7517 ! I won't have time to do a deep review in the short term but this is already a nice base. Ideally, we should try to use this interface already, e.g. in the LHCb masterclass, to validate that it fulfills the needs. This will obviously take some time

hello @sponce I agree, real validation in the LHCb masterclass is the right next step. I can create a minimal integration prototype and report back on what works well and what should be improved in the interface. Then we can do small targeted follow-up changes based on that validation.

[sponce]

For an integration prototype, we'll have to organize it as you will need access to the LHCb code. Let's sort this out once the GSoC selections are over if you're selected.

[GaneshPatil7517]

For an integration prototype, we'll have to organize it as you will need access to the LHCb code. Let's sort this out once the GSoC selections are over if you're selected.

Thanks @sponce, that sounds great! I'll keep this PR focused on the core callback API for now and make sure everything is solid with tests and documentation. Happy to coordinate on the LHCb integration prototype once selections are done. Looking forward to it!