feat: add use-arrow-clusters react hook package

[aysead]

Hi @StoneTapeStudios,

As discussed, I've created the initial structure for the use-arrow-clusters hook as a separate package to keep the core framework-agnostic.

What's included in this draft:
Scaffolded a new "use-arrow-clusters" package within the monorepo ("package.json", "tsdown", "tsconfig").
Implemented the "useArrowClusters" hook with the dual "useMemo" approach we talked about:

1. Expensive operation: "engine.load()" only runs when the "table" reference or core "options" change.
2. Cheap operation: "engine.getClusters()" runs when the map viewport ("bounds" / "zoom") updates.

Next steps to discuss:
Before I add tests and update the README with the usage examples (and the note about Arrow Table reference stability), I wanted to get your feedback on this initial structure and the hook's API signature.

Let me know if this direction looks good to you!

[StoneTapeStudios]

@aysead Great start, left some feedback on the memo deps and types — let me know what you think

[aysead]

Hi @StoneTapeStudios,
Thank you for the detailed review and the great catch on the useMemo dependencies. I've updated the dependency arrays to prevent those unnecessary re-calculations. I also applied the other suggestions:

• Reused ArrowClusterEngineOptions from the main package.
• Exposed idColumn as an optional parameter.
• Exported the UseArrowClustersResult interface.
  I just pushed the updated commits. Thanks again for the guidance.

[aysead]

Hi @StoneTapeStudios, I've just pushed the missing package.json and pnpm-lock.yaml files so the CI can find the test dependencies. It looks like the GitHub Actions workflow is waiting for a maintainer's approval to run ('Action required'). Could you please approve the workflow run when you have a chance? Thanks again for all the guidance.

[StoneTapeStudios]

@aysead Nice work on this iteration — the hook structure is clean and the dependency array improvements from the last round are solid. Left another round of feedback, mostly around tightening up the tests and a few small consistency items.

The main ones:

• The test mock should return a proper ClusterOutput shape instead of [] — the other packages' tests have a makeOutput() pattern worth following here
• Missing a memoization stability test (verifying the engine isn't re-created when only bounds/zoom change), which is the core thing this hook is supposed to guarantee
• A few small housekeeping items: missing test script, quote consistency

Also left a note on the useMemo + engine.load() tradeoff — not a blocker, just something to be aware of given how heavy load() is compared to the vanilla Supercluster equivalent.

Let me know if any of the comments need clarification.

[aysead]

Hi @StoneTapeStudios,

I've just pushed the final updates:

Updated the test mock to return a proper ClusterOutput shape using a makeOutput() helper.

Added the missing memoization stability test to verify the engine isn't re-created unnecessarily.

Refactored the hook to use the useRef manual memoization pattern for safer engine stability, as you suggested.

Fixed the minor housekeeping items (test script in package.json, quote consistency, and the README wording).

Ready for your review.

[StoneTapeStudios]

Hey @aysead ,

Everything looks great! Thanks so much for your work on this. Eventually it'd be nice if we had a React example in the examples folder.

I'd be interested to see/hear how you're using the package.

All the best 🙏