Add declusteredEvent to EntityCluster

[Oko-Tester]

Fixes #5760 by adding declusteredEvent that provides both clustered and declustered entities, plus new API methods for accessing clustering state. Maintains backward compatibility.

Description

This PR adds comprehensive clustering state information to EntityCluster by introducing a new declusteredEvent and supporting API methods. The original clusterEvent only provided information about entities that were successfully clustered, but developers also needed access to entities that were processed but not clustered (declustered entities).

Key Changes

• New declusteredEvent: Fires with complete clustering information including both clustered and declustered entities
• New API methods:
  • getLastClusteredEntities() - Returns currently clustered entities
  • getLastDeclusteredEntities() - Returns currently declustered entities
  • getAllProcessedEntities() - Returns all entities processed during clustering
• Enhanced event coverage: Events now fire when clustering is disabled or clusters become empty
• Backward compatibility: Original clusterEvent remains unchanged and functional

Issue number and link

Fixes #5760 - Include declustered entities in cluster callback

This addresses multiple user requests from the forum and GitHub comments spanning several years.

Testing plan

Manual Testing

1. Create CustomDataSource with clustering enabled
2. Add entities at various distances to create both clustered and declustered entities
3. Verify declusteredEvent fires with correct clustered and declustered arrays
4. Disable clustering and verify event fires with all entities as declustered
5. Test API methods return correct entity lists
6. Verify original clusterEvent still works as before

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @Oko-Tester!

✅ We can confirm we have a CLA on file for you.

[Oko-Tester]

this is ready

[Oko-Tester]

@mzschwartz5 Is there any news regarding the approval?