Better support for custom links

[jdharrisnz]

Hi all,

I'm using React Aria Components. For creating custom links, there are two ways to do it:

1. Create a TSR-flavoured Link by following this guide https://tanstack.com/router/latest/docs/framework/react/guide/custom-link#react-aria-components-example
2. Create a RAC-flavoured Link by following this guide https://react-spectrum.adobe.com/react-aria/routing.html#tanstack-router

Option 1 is the more full-featured way to do it, but there are several clashes with RAC when doing something like createLink(AriaLink):

1. The type of the component generated by this function suggests that the function-form className and style props will work in the RAC way, but in fact they only work in the TSR way because TSR's useLinkProps gobbles the input.
2. It's not clear whether RAC interaction props (such as onHover, onPress, etc) will be properly used or merged with the resulting component.
3. There are a few clashing props, such as TSR's disabled vs RAC's isDisabled, which both show up in the result.

So it's just not a very nice result.

Next, for option 2, setting up the RAC's RouterProvider and type declaration is just good practice in any case, since it integrates with more components than just Link. With this method, you get a Link component that avoids all of the above weird TypeScript issues and has consistent prop types. The autocomplete support in the href prop using the type declaration is fine, but not perfect, though this can be fixed by wrapping input in the linkOptions function. What's missing?

1. Preload
2. data-status="active"

Both of the above are handled by inline code inside TSR's useLinkProps hook.

I would like to suggest that this lib extracts the relevant code into exported hooks, so that consumers can augment their own Link components with usePreload and useIsLinkActive.

For the time being, I've done this myself by writing my own hooks from looking at the source code. I needed these three:

1. useToOptions: (options: ToOptions) => ToOptions, returns input ToOptions with the fallback from prop filled by the leaf match from useMatches if from wasn't in the input
2. useIsLinkActive: (toOptions: ToOptions, activeOptions?: ActiveOptions) => boolean

And usePreload (types come from my own Link component, but it's just a combination of TSR Link and RAC Link):

usePreload: ({ href, routerOptions, preload, preloadDelay, isDisabled, }: Pick<Link.Props, "href" | "routerOptions" | "preload" | "preloadDelay" | "isDisabled">) => {
    readonly intersectionRef: React.RefObject<HTMLAnchorElement | null>;
    readonly handleFocus: () => void;
    readonly handleEnter: () => void;
    readonly handleLeave: () => void;
}

In my case, I just manually merge the event handlers from usePreload with any supplied in props into RAC's Link.

usePreload also requires useIntersectionObserver obviously, which I think for now is just an internal function not exported for consumers.

Thoughts?