Why are previously public utilities now bundled as private?

[Pearce-Ropion]

Why are previously public utilities now bundled as private? I know they can still be imported from the private path but I don't understand why they are marked as "private". Part of the idea of the headless API is that you can build custom behavior/hooks using the same internals as what the primary hook API offers. In order to do so, you pretty much have to use these private utils.

For example, previously I could import { focusSafely } from '@react-aria/focus. Now I have to go fetch this utility from a "private" path: import { focusSafely } from 'react-aria/private/interactions/focusSafely'

Instead, I propose that the now private utils should be just exported as standard utils using the existing "exports": "./*" wildcard system. So in my above example, the import would instead be import { focusSafely } from 'react-aria/interactions/focusSafely'

[devongovett]

These were never publicly documented. Yes you can import them but that doesn't mean we recommend their use.

[Pearce-Ropion]

Got it. Thanks!

[b3nten]

Is it still valid to import these directly from @react-aria/collections, or is that not recommended? Reason I ask is because certain things like useIsHidden() appears required to integrate hook-based components with RAC components that use collections, it's private in react-aria-components but exported seemingly publicly from @react-aria/collections.

#5912 seems to suggest that access to these collection exports is intended for public usage, but only createLeafComponent and createBranchComponent are exported from react-aria-components/CollectionBuilder, and not others like useIsHidden().

The docs for Lists, Menu, Tabs etc explicitly import ItemNode from react-aria/private/collections/BaseCollection, and FocusableProvider is another example of private usage in the docs, when it's a public export from @react-aria/interactions.

The reason I ask is because there are cases where I'd like to build my own components using the hooks, but keep compatibility with other RAC components without needing to reimplement everything. Utility functions are not a big deal to reimplement but even the examples for things like Menu use these private exports, useIsHidden seems relevant for hook-based popovers in form controls, useModal for combining hook-based and RAC modals, etc.

Are they not recommended for use because users should generally use the prebuilt components, or are they not recommended for use because they may change between patches and are unstable? And since the individual @react-aria/* packages alias private exports, what kind of contract do we have with those packages?

[snowystinger]

We should not be importing from private in the docs, that should be fixed. Thanks for flagging that.

@react-aria is a legacy scope, we kept a lot of things in there as they were when the code was organised into each of those individually because we were aware that the line was a little fuzzy/confusing as to what was public and what was private and we didn't want to break people by changing those exports.

We instead recommend using the packages react-aria-components, react-aria, and react-stately. The latter two more if you need access to the hooks.

Collections are additionally confusing because there are two implementations. As you've found, you can follow the examples in our hooks docs for how to build on the newer implementation. https://react-aria.adobe.com/ListBox/useListBox

In general, the goal is that you can use RAC for almost everything, but when you need to dip into a lower level, you can do that and just re-implement that one component. We don't know how commonly people need to do this, we've not needed it for our own React Spectrum S2.

There may be some things which were missed that should have been public when we reorganised the entire repo. useIsHidden may be one of those. What do the React Aria Components not provide that you need to re-implement Popovers and Modals with hooks instead of using the component? It should be noted, those components can be pretty tricky to implement with the hooks. Happy to consider adding it nonetheless.
The ones we used in the docs should definitely be public though.

[b3nten]

Hi, thanks for the quick response. Will stick to imports from those three packages.

From my analysis, the main thing I'd like to use is HiddenContext since so many components consume it via createHidableComponent or useIsHidden, primarily Button, inputs, Text, and overlays. Eg. I'd like to create my own Button and/or Popover instead of wrapping the components but then I lose support for collections - or at least I think I do, I don't yet understand the implications of omitting hidable support - perhaps it's fine? There is also ItemNode which some of the examples use.

The full list of exports that cannot be trivially re-implemented in usercode would be PressResponder, FocusableProvider, FormValidationContext, isVirtualDragging, getInteractionModality, RouterProvider, and OverlayContainer, and these are mainly because the consume a private context, but these are much less important from what I can see. There are some others like annouce and focusSafely which would cause some code duplication if vendoring, but again this is less of a problem since they're mostly independent.

Now I understand there are very good reasons for not making everything public so I'm not suggesting to publicly export all of these, I would just say these are the ones that devs would want if they were using the hooks.

What do the React Aria Components not provide that you need to re-implement Popovers and Modals with hooks instead of using the component?

Some of this is due to how components use contexts, eg #10626. In my case it's the OverlayArrowContext in Popover/Tooltip, but I feel I might run into the same issue with input components as well. This is a fairly niche problem because I make use of the render prop more than most. And for some components there are some performance optimisations I'd like to make which are extremely specific to our usecases, where dropping down to the hooks would make it possible.

Would you like me to open an issue on this topic?

[snowystinger]

I think just opening an Issue covering the needed exports would be good. I think there are already a couple open issues which may partially cover the work, so maybe check for that first.