Add docs for links in collections and client side routing guide (#5078)

Author: devongovett

packages/@adobe/react-spectrum/package.json

@@ -26,6 +26,7 @@
   "dependencies": {
     "@react-aria/i18n": "^3.8.2",
     "@react-aria/ssr": "^3.8.0",
+    "@react-aria/utils": "^3.20.0",
     "@react-aria/visually-hidden": "^3.8.4",
     "@react-spectrum/actionbar": "^3.2.0",
     "@react-spectrum/actiongroup": "^3.9.2",

packages/@adobe/spectrum-css-temp/components/breadcrumb/index.css

@@ -102,8 +102,7 @@ governing permissions and limitations under the License.
   margin-block-end: 0;
   font-size: inherit;
 
-  &[href],
-  &[tabindex="0"] {
+  &:not([aria-disabled]) {
     cursor: pointer;
 
     &:hover,

packages/@adobe/spectrum-css-temp/components/table/index.css

@@ -370,6 +370,10 @@ svg.spectrum-Table-sortedIcon {
   cursor: default;
   transition: background-color var(--spectrum-global-animation-duration-100) ease-in-out;
 
+  &[data-href] {
+    cursor: pointer;
+  }
+
   &:focus {
     outline: 0;
   }

packages/@react-aria/autocomplete/docs/useSearchAutocomplete.mdx

@@ -572,6 +572,10 @@ function AsyncLoadingExample() {
 }
 ```
 
+### Links
+
+By default, interacting with an item in a SearchAutocomplete updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component. Interacting with link items navigates to the provided URL and does not update the input value. See the [links](useListBox.html#links) section in the `useListBox` docs for details on how to support this.
+
 ## Internationalization
 
 `useSearchAutocomplete` handles some aspects of internationalization automatically.

packages/@react-aria/combobox/docs/useComboBox.mdx

@@ -671,6 +671,10 @@ function AsyncLoadingExample() {
 }
 ```
 
+### Links
+
+By default, interacting with an item in a ComboBox selects it and updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component. Interacting with link items navigates to the provided URL and does not update the selection or input value. See the [links](useListBox.html#links) section in the `useListBox` docs for details on how to support this.
+
 ## Internationalization
 
 `useComboBox` handles some aspects of internationalization automatically.

packages/@react-aria/gridlist/docs/useGridList.mdx

@@ -17,6 +17,7 @@ import selectionDocs from 'docs:@react-stately/selection';
 import statelyDocs from 'docs:@react-stately/list';
 import focusDocs from 'docs:@react-aria/focus';
 import checkboxDocs from 'docs:@react-aria/checkbox';
+import utilsDocs from 'docs:@react-aria/utils';
 import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, TypeLink, PageDescription} from '@react-spectrum/docs';
 import {Keyboard} from '@react-spectrum/text';
 import packageData from '@react-aria/gridlist/package.json';
@@ -484,6 +485,29 @@ This behavior is slightly different when `selectionBehavior="replace"`, where si
 </div>
 ```
 
+### Links
+
+Items in a GridList may also be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component. Links behave the same way as described above for row actions depending on the `selectionMode` and `selectionBehavior`.
+
+```tsx example
+<List aria-label="Links" selectionMode="multiple">
+  <Item href="https://adobe.com/" target="_blank">Adobe</Item>
+  <Item href="https://apple.com/" target="_blank">Apple</Item>
+  <Item href="https://google.com/" target="_blank">Google</Item>
+  <Item href="https://microsoft.com/" target="_blank">Microsoft</Item>
+</List>
+```
+
+```css hidden
+.list li[data-href] {
+  cursor: pointer;
+}
+```
+
+#### Client side routing
+
+The `<Item>` component works with frameworks and client side routers like [Next.js](https://nextjs.org/) and [React Router](https://reactrouter.com/en/main). As with other React Aria components that support links, this works via the <TypeLink links={utilsDocs.links} type={utilsDocs.exports.RouterProvider} /> component at the root of your app. See the [client side routing guide](routing.html) to learn how to set this up.
+
 ### Asynchronous loading
 
 This example uses the [useAsyncList](../react-stately/useAsyncList.html) hook to handle asynchronous loading of data from a server. You may additionally want to display a spinner to indicate the loading state to the user, or support features like infinite scroll to load more data.

packages/@react-aria/gridlist/src/useGridListItem.ts

@@ -178,7 +178,7 @@ export function useGridListItem<T>(props: AriaGridListItemOptions, state: ListSt
     }
   };
 
-  let linkProps = getSyntheticLinkProps(node.props);
+  let linkProps = itemStates.hasAction ? getSyntheticLinkProps(node.props) : {};
   let rowProps: DOMAttributes = mergeProps(itemProps, linkProps, {
     role: 'row',
     onKeyDownCapture: onKeyDown,

packages/@react-aria/link/docs/useLink.mdx

@@ -76,8 +76,6 @@ function Link(props) {
     <a
       {...linkProps}
       ref={ref}
-      href={props.href}
-      target={props.target}
       style={{color: 'var(--blue)'}}>
       {props.children}
     </a>
@@ -136,8 +134,6 @@ function Link(props) {
     <a
       {...linkProps}
       ref={ref}
-      href={props.href}
-      target={props.target}
       style={{
         color: props.isDisabled ? 'var(--gray)' : 'var(--blue)',
         cursor: props.isDisabled ? 'default' : 'pointer'

packages/@react-aria/link/src/useLink.ts

@@ -12,8 +12,8 @@
 
 import {AriaLinkProps} from '@react-types/link';
 import {DOMAttributes, FocusableElement} from '@react-types/shared';
-import {filterDOMProps, mergeProps} from '@react-aria/utils';
-import {RefObject} from 'react';
+import {filterDOMProps, mergeProps, shouldClientNavigate, useRouter} from '@react-aria/utils';
+import React, {RefObject} from 'react';
 import {useFocusable} from '@react-aria/focus';
 import {usePress} from '@react-aria/interactions';
 
@@ -62,6 +62,7 @@ export function useLink(props: AriaLinkOptions, ref: RefObject<FocusableElement>
   let {pressProps, isPressed} = usePress({onPress, onPressStart, onPressEnd, isDisabled, ref});
   let domProps = filterDOMProps(otherProps, {labelable: true, isLink: elementType === 'a'});
   let interactionHandlers = mergeProps(focusableProps, pressProps);
+  let router = useRouter();
 
   return {
     isPressed, // Used to indicate press state for visual
@@ -70,12 +71,25 @@ export function useLink(props: AriaLinkOptions, ref: RefObject<FocusableElement>
       ...linkProps,
       'aria-disabled': isDisabled || undefined,
       'aria-current': props['aria-current'],
-      onClick: (e) => {
+      onClick: (e: React.MouseEvent<HTMLAnchorElement>) => {
         pressProps.onClick?.(e);
         if (deprecatedOnClick) {
           deprecatedOnClick(e);
           console.warn('onClick is deprecated, please use onPress');
         }
+
+        // If a custom router is provided, prevent default and forward if this link should client navigate.
+        if (
+          !router.isNative &&
+          e.currentTarget instanceof HTMLAnchorElement &&
+          e.currentTarget.href &&
+          // If props are applied to a router Link component, it may have already prevented default.
+          !e.isDefaultPrevented() &&
+          shouldClientNavigate(e.currentTarget, e)
+        ) {
+          e.preventDefault();
+          router.open(e.currentTarget, e);
+        }
       }
     })
   };