chore: add deprecation tag to 'to' prop on Link primitive (#2265)

* chore: deprecate 'to' prop on Link primitive

* chore: update yarn.lock

* Create slimy-pugs-travel.md

* chore: address comments

* chore: add space to warning message to remove LGTM alert

Author: zchenwei

.changeset/slimy-pugs-travel.md

@@ -0,0 +1,5 @@
+---
+"@aws-amplify/ui-react": patch
+---
+
+chore: add deprecation tag to 'to' prop on Link primitive

docs/src/pages/[platform]/components/link/props-table.mdx

@@ -106,7 +106,7 @@ string
 string
 ```
 </TableCell>
-      <TableCell className="props-table__tr-description">A string representation of the URL path</TableCell>
+      <TableCell className="props-table__tr-description">The Link component's to prop will soon be deprecated. Please see the Amplify UI documentation for using the Link component with routing libraries: https://ui.docs.amplify.aws/react/components/link#routing-libraries A string representation of the URL path</TableCell>
     </TableRow>
 
   </TableBody>

docs/src/pages/[platform]/components/link/react.mdx

@@ -47,7 +47,7 @@ To create a Link which opens in a new tab, use the `isExternal` prop. Under the
 
 ### Routing Libraries
 
-To use the Link with React routing libraries, pass in routing components to the `as` prop. Below is an example using React Router:
+You can use a Link with any React routing library that supports custom components. Below is an example using Link with React Router v5, in which the Link is passed to the `component` prop as a custom navigation component:
 
 <Example>
   <ExampleCode>
@@ -61,13 +61,25 @@ To use the Link with React routing libraries, pass in routing components to the
       Route,
     } from 'react-router-dom';
 
+    function Home() {
+      return <Heading level={2}>Home</Heading>;
+    }
+
+    function About() {
+      return <Heading level={2}>About</Heading>;
+    }
+
+    function Users() {
+      return <Heading level={2}>Users</Heading>;
+    }
+
     function App() {
       return (
         <Router>
           <Flex>
-            <Link as={ReactRouterLink} to="/">Home</Link>
-            <Link as={ReactRouterLink} to="/about">About</Link>
-            <Link as={ReactRouterLink} to="/users">Users</Link>
+            <ReactRouterLink to="/" component={Link}>Home</ReactRouterLink>
+            <ReactRouterLink to="/about" component={Link}>About</ReactRouterLink>
+            <ReactRouterLink to="/users" component={Link}>Users</ReactRouterLink>
           </Flex>
 
           <Routes>
@@ -79,18 +91,6 @@ To use the Link with React routing libraries, pass in routing components to the
       );
     }
 
-    function Home() {
-      return <Heading level={2}>Home</Heading>;
-    }
-
-    function About() {
-      return <Heading level={2}>About</Heading>;
-    }
-
-    function Users() {
-      return <Heading level={2}>Users</Heading>;
-    }
-
     export default App;
     ```
   </ExampleCode>

packages/react/src/primitives/Link/Link.tsx

@@ -4,11 +4,19 @@ import classNames from 'classnames';
 import { ComponentClassNames } from '../shared';
 import { LinkProps, Primitive } from '../types';
 import { View } from '../View';
+import { useDeprecationWarning } from '../../hooks/useDeprecationWarning';
 
 const LinkPrimitive: Primitive<LinkProps, 'a'> = (
   { as = 'a', children, className, isExternal, to, ...rest },
   ref
 ) => {
+  useDeprecationWarning({
+    shouldWarn: to != null,
+    message:
+      "The Link component's to prop will soon be deprecated. " +
+      'Please see the Amplify UI documentation for using the Link component with routing libraries: ' +
+      'https://ui.docs.amplify.aws/react/components/link#routing-libraries',
+  });
   return (
     <View
       as={as}

packages/react/src/primitives/Link/__tests__/Link.test.tsx

@@ -1,10 +1,8 @@
 import * as React from 'react';
-import kebabCase from 'lodash/kebabCase';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 import { ComponentClassNames } from '../../shared';
-import { ComponentPropsToStylePropsMap } from '../../types';
 import { Link } from '../Link';
 import { Text } from '../../Text/Text';
 import { Flex } from '../../Flex';
@@ -117,4 +115,11 @@ describe('Link: ', () => {
 
     expect(screen.getByText(/you are on the about page/i)).toBeInTheDocument();
   });
+
+  it('should call console.warn if "to" prop is used', async () => {
+    const spyWarn = jest.spyOn(console, 'warn');
+    render(<Link to="/test">Test</Link>);
+    expect(spyWarn).toHaveBeenCalled();
+    spyWarn.mockRestore();
+  });
 });

packages/react/src/primitives/types/link.ts

@@ -16,6 +16,10 @@ export interface LinkOptions {
   isExternal?: boolean;
 
   /**
+   * @deprecated
+   * The Link component's to prop will soon be deprecated.
+   * Please see the Amplify UI documentation for using the Link component with routing libraries:
+   * https://ui.docs.amplify.aws/react/components/link#routing-libraries
    * @description
    * A string representation of the URL path
    */