Promote useViewportSize to a public, documented hook

[onlywei]

🙋 Documentation Request

useViewportSize is exported from @react-aria/utils and usable by consumers, but it has no documentation page and its source lives under the private/ folder within the package. This sends mixed signals about whether it's intended for external use or could change without notice.

The ask

• Add a documentation page to the React Aria docs site (usage, SSR behavior, return type)
• Clarify the hook's public API status — if the private/ source directory is just organizational and not a stability signal, a docs page would resolve that ambiguity on its own

Context

Multiple SSR-related issues (#4676, #4921, #5057) have been filed by consumers who discovered this hook through Modal and Popover internals. People are already depending on it and would benefit from official guidance. It's also a notably better alternative to popular community hooks like usehooks-ts/useWindowSize thanks to its visualViewport usage, but there's no way to discover that without reading the source.

🧢 Your Company/Team

No response

[snowystinger]

Due to our old repo organization and architecture, many things had to be exported so they could be shared between packages. This meant things we regarded as private as well, which wasn't always clear. We tended to lean on, if it's not documented, it's considered private, we do not guarantee its API. So that's why you're seeing the current state of it like this.

We can definitely consider on a case by case basis promoting things from private to public with official docs and I think this is one worth talking about.

Will bring up with the team and see if we can get a consensus on this

[nwidynski]

@snowystinger I think it would be better to consider promotion of useResizeObserver. useViewportSize could essentially just be a tiny state wrapper around it, once its expanded for window and visualViewport.

[snowystinger]

We had a chat about this. It's a pretty small hook with no dependencies and we would prefer to reserve the right to change it for our own usage in the future. We think that if users would like to use it, they can copy it.

There was a previous conversation around useResizeObserver, useResizeObserver - not triggered on first render for older browsers which we revisited as part of this. If we exposed these hooks, then we would need to possibly fix other bugs that aren't pertinent to our own use case. That's more overhead and more work.

I'm going to close both of these. Thank you for understanding.