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?

[mzschwartz5]

Hi @Oko-Tester, I haven't had a chance to review this yet. It might not happen until Thursday as I'm out tomorrow and Wednesday.

[mzschwartz5]

Hey @Oko-Tester,

Thanks for the PR. I have a number of mostly minor comments about code style and performance, but those might be irrelevant because I'm a little unsure of the overall approach. It's a lot of extra state that we're tracking now, which means more memory consumed, more bookkeeping to sync arrays, more room for potential edge cases.

In the linked issue you said "clusterEvent does not fire when a cluster becomes empty, which makes it impossible to detect de-clustered entities." My intuition is that there's a better way to deal with this than to track more state and manually fire the decluster event accordingly. I haven't actually looked at the code closely to tell, but that's my instinct.

[mzschwartz5]

I'm not an expert on unit testing philosphy, so maybe this is a bad suggestion, but could we maybe have unit test(s) that check that clustering generally works for all three of: points, billboards, and labels (collections)?

I'm just a little wary given the discussion about using the item.show property as if these classes all have a shared abstract interface (which they don't). I don't expect that to be an issue, but if someone were to ever change that property name on one of the classes, at least having a failing unit test here would prevent the issue.

[Oko-Tester]

Hey @mzschwartz5,
Thanks for your feedback. I'll rethink my current implementation and maybe find a better way. But I won't be able to deal with this MR for a few days.

As for your comment on unit tests, I am not an expert in this field either, but it seems sensible to me to use them to avoid potential future problems.

[Oko-Tester]

Okay, I rethought my current implementation and realized that I had adapted the component too much for my specific needs.
It would be better to simply add a single event that returns the last declustered entities — nothing more. The rest can easily be handled manually by the user.

I’ve reset the EntityCluster component locally and will commit the new changes shortly after testing them. I also need to update the tests to match the new implementation.

I’d really appreciate your feedback on this new approach once the changes are pushed.

[mzschwartz5]

@Oko-Tester When you're ready, just re-request review from me and/or leave a comment saying you're ready for another pass. Depending on when it's ready, I may need a few days before I can take another look.