Adding deprecation warnings to icons (#1343)

Co-authored-by: Chenwei Zhang <40295569+zchenwei@users.noreply.github.com>
Co-authored-by: Scott Rees <6165315+reesscot@users.noreply.github.com>

.changeset/honest-toes-march.md

@@ -0,0 +1,5 @@
+---
+"@aws-amplify/ui-react": patch
+---
+
+Adding deprecation warnings to icons

docs/src/components/Layout/Header.tsx

@@ -1,22 +1,24 @@
 import * as React from 'react';
 import NextLink from 'next/link';
 import {
-  IconOpenInNew,
   Button,
   VisuallyHidden,
   Link,
   Flex,
   ColorMode,
   ToggleButton,
   ToggleButtonGroup,
-  IconWbSunny,
-  IconBedtime,
-  IconTonality,
-  IconMenu,
   Divider,
   View,
-  IconClose,
 } from '@aws-amplify/ui-react';
+import {
+  MdClose,
+  MdMenu,
+  MdWbSunny,
+  MdBedtime,
+  MdTonality,
+  MdOpenInNew,
+} from 'react-icons/md';
 import { useRouter } from 'next/router';
 import { Logo } from '@/components/Logo';
 import { FrameworkChooser } from './FrameworkChooser';
@@ -67,7 +69,7 @@ const Nav = (props) => (
     </NavLink>
     <Divider orientation="vertical" />
     <NavLink {...props} isExternal href="https://docs.amplify.aws">
-      Amplify docs <IconOpenInNew />
+      Amplify docs <MdOpenInNew />
     </NavLink>
   </Flex>
 );
@@ -90,15 +92,15 @@ const ColorModeSwitcher = ({ colorMode, setColorMode }) => {
     >
       <ToggleButton value="light">
         <VisuallyHidden>Light mode</VisuallyHidden>
-        <IconWbSunny />
+        <MdWbSunny />
       </ToggleButton>
       <ToggleButton value="dark">
         <VisuallyHidden>Dark mode</VisuallyHidden>
-        <IconBedtime />
+        <MdBedtime />
       </ToggleButton>
       <ToggleButton value="system">
         <VisuallyHidden>System preference</VisuallyHidden>
-        <IconTonality />
+        <MdTonality />
       </ToggleButton>
     </ToggleButtonGroup>
   );
@@ -115,7 +117,7 @@ export const Header = ({ platform, colorMode, setColorMode }) => {
           onClick={() => setExpanded(!expanded)}
           ariaLabel="Docs header menu button"
         >
-          {expanded ? <IconClose /> : <IconMenu />}
+          {expanded ? <MdClose /> : <MdMenu />}
         </Button>
 
         <NavLink href="/">

docs/src/components/Layout/index.tsx

@@ -1,14 +1,15 @@
 import * as React from 'react';
 import debounce from 'lodash/debounce';
-import { SiW3C, SiReact } from 'react-icons/si';
 import {
+  Icon,
   Heading,
   Link,
-  Icon,
   Text,
   View,
   useTheme,
 } from '@aws-amplify/ui-react';
+import { SiW3C, SiReact } from 'react-icons/si';
+
 import { Sidebar } from './SecondaryNav';
 import { TableOfContents } from '../TableOfContents';
 import { Footer } from './Footer';

docs/src/pages/HomePrimitivePreview.tsx

@@ -25,6 +25,12 @@ import {
   Menu,
   MenuItem,
 } from '@aws-amplify/ui-react';
+import {
+  MdFormatAlignLeft,
+  MdFormatAlignRight,
+  MdFormatAlignCenter,
+  MdFormatAlignJustify,
+} from 'react-icons/md';
 
 export const HomePrimitivePreview = () => {
   const [exclusiveValue, setExclusiveValue] = React.useState('align-left');
@@ -57,17 +63,17 @@ export const HomePrimitivePreview = () => {
           isExclusive
           onChange={(value: string) => setExclusiveValue(value)}
         >
-          <ToggleButton value="align-left" ariaLabel="align-left">
-            <IconFormatAlignLeft />
+          <ToggleButton value="align-left" ariaLabel="align left">
+            <MdFormatAlignLeft />
           </ToggleButton>
-          <ToggleButton value="align-center" ariaLabel="align-center">
-            <IconFormatAlignCenter />
+          <ToggleButton value="align-center" ariaLabel="align center">
+            <MdFormatAlignCenter />
           </ToggleButton>
-          <ToggleButton value="align-right" ariaLabel="align-right">
-            <IconFormatAlignRight />
+          <ToggleButton value="align-right" ariaLabel="align right">
+            <MdFormatAlignRight />
           </ToggleButton>
-          <ToggleButton value="align-justify" ariaLabel="align-justify">
-            <IconFormatAlignJustify />
+          <ToggleButton value="align-justify" ariaLabel="align justify">
+            <MdFormatAlignJustify />
           </ToggleButton>
         </ToggleButtonGroup>
         <Button variation="primary">Get started</Button>

docs/src/pages/components/icon/react.mdx

@@ -1,4 +1,4 @@
-import { Button, Icon, Flex, Text } from '@aws-amplify/ui-react';
+import { Button, Icon, Flex, Text, Alert } from '@aws-amplify/ui-react';
 import { IconDemo } from './demo';
 import { AllIcons } from './AllIcons';
 import { Example, ExampleCode } from '@/components/Example';
@@ -41,6 +41,13 @@ Import the Icon component and styles.
 
 ### Built-in iconset
 
+<Alert variation="warning" heading="Deprecated">
+  The built-in icons are being removed in the next major release. You can use
+  the [react-icons](https://react-icons.github.io/react-icons) package or other
+  React icon libraries in its place. `import {ICON_NAME} from
+  '@aws-amplify/ui-react';` becomes `import {ICON_NAME} from 'react-icons/md';`
+</Alert>
+
 Use a default icon from the [Material Design icons](http://google.github.io/material-design-icons/).
 
 <Example>

examples/next/pages/examples/listings/App.tsx

@@ -21,7 +21,6 @@ export const App = ({ children }) => {
     <AmplifyProvider theme={theme} colorMode={colorMode}>
       <header className="listing-app-header">
         <Logo />
-
         <input type="search" placeholder="search" />
         <ToggleButtonGroup
           value={colorMode}

packages/react/scripts/generateIcons.js

@@ -6,26 +6,74 @@ const dirPath = `./src/primitives/Icon/icons/`;
 const iconSetPath = '../ui/src/icons/*.svg';
 const iconNames = [];
 
-const template = ({ iconName, source }) => `import classNames from 'classnames';
-
-import { ComponentClassNames } from '../../shared';
-import { View } from '../../View';
-
-export const ${iconName} = (props) => {
-  const { className, ...rest } = props;
-  return (
-    <View
-      as='span'
-      width='1em'
-      height='1em'
-      className={classNames(ComponentClassNames.Icon, className)}
-      {...rest}
-    >
-      ${source.replace('black', 'currentColor')}
-    </View>
-  );
-}
+const INTERNAL_ICONS = [
+  'Icon',
+  'IconAdd',
+  'IconCheck',
+  'IconCheckCircle',
+  'IconCheckCircleOutline',
+  'IconChevronLeft',
+  'IconChevronRight',
+  'IconClose',
+  'IconError',
+  'IconExpandMore',
+  'IconFiberManualRecord',
+  'IconHighlightOff',
+  'IconInfo',
+  'IconMenu',
+  'IconRemove',
+  'IconSearch',
+  'IconStar',
+  'IconVisibility',
+  'IconVisibilityOff',
+  'IconWarning',
+];
+
+const template = ({ iconName, source }) => {
+  const isDeprecatedIcon = !INTERNAL_ICONS.includes(iconName);
+  const deprecationJSDoc = `/**
+   * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. \`import { ${iconName} } from '@aws-amplify/ui-react';\` → \`import { Md${iconName.replace(
+    'Icon',
+    ''
+  )} } from 'react-icons/md';\`
+   */`;
+  const importDeprecationWarning = isDeprecatedIcon
+    ? `import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';`
+    : '';
+  const useDeprecationWarningCode = isDeprecatedIcon
+    ? `useDeprecationWarning({
+    shouldWarn: ${isDeprecatedIcon},
+    message: \`Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.\nimport { ${iconName} } from '@aws-amplify/ui-react'; → import { Md${iconName.replace(
+        'Icon',
+        ''
+      )} } from 'react-icons/md';\`,
+  });`
+    : '';
+
+  return `import classNames from 'classnames';
+
+  import { ComponentClassNames } from '../../shared';
+  import { View } from '../../View';
+  ${importDeprecationWarning}
+
+  ${isDeprecatedIcon ? deprecationJSDoc : ''}
+  export const ${iconName} = (props) => {
+    const { className, ...rest } = props;
+    ${useDeprecationWarningCode}
+    return (
+      <View
+        as='span'
+        width='1em'
+        height='1em'
+        className={classNames(ComponentClassNames.Icon, className)}
+        {...rest}
+      >
+        ${source.replace('black', 'currentColor')}
+      </View>
+    );
+  }
 `;
+};
 
 fs.ensureDirSync(dirPath);
 glob(iconSetPath, function (error, files) {

packages/react/src/primitives/Icon/icons/Icon360.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { Icon360 } from '@aws-amplify/ui-react';` → `import { Md360 } from 'react-icons/md';`
+ */
 export const Icon360 = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { Icon360 } from '@aws-amplify/ui-react'; → import { Md360 } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/Icon3dRotation.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { Icon3dRotation } from '@aws-amplify/ui-react';` → `import { Md3dRotation } from 'react-icons/md';`
+ */
 export const Icon3dRotation = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { Icon3dRotation } from '@aws-amplify/ui-react'; → import { Md3dRotation } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/Icon4k.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { Icon4k } from '@aws-amplify/ui-react';` → `import { Md4k } from 'react-icons/md';`
+ */
 export const Icon4k = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { Icon4k } from '@aws-amplify/ui-react'; → import { Md4k } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/Icon5g.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { Icon5g } from '@aws-amplify/ui-react';` → `import { Md5g } from 'react-icons/md';`
+ */
 export const Icon5g = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { Icon5g } from '@aws-amplify/ui-react'; → import { Md5g } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/Icon6FtApart.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { Icon6FtApart } from '@aws-amplify/ui-react';` → `import { Md6FtApart } from 'react-icons/md';`
+ */
 export const Icon6FtApart = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { Icon6FtApart } from '@aws-amplify/ui-react'; → import { Md6FtApart } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/IconAcUnit.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { IconAcUnit } from '@aws-amplify/ui-react';` → `import { MdAcUnit } from 'react-icons/md';`
+ */
 export const IconAcUnit = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { IconAcUnit } from '@aws-amplify/ui-react'; → import { MdAcUnit } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"

packages/react/src/primitives/Icon/icons/IconAccessAlarm.tsx

@@ -2,9 +2,18 @@ import classNames from 'classnames';
 
 import { ComponentClassNames } from '../../shared';
 import { View } from '../../View';
+import { useDeprecationWarning } from '../../../hooks/useDeprecationWarning';
 
+/**
+ * @deprecated These icons are being removed in the next major release. You can use the [react-icons](https://react-icons.github.io/react-icons) package or other React icon libraries in its place. `import { IconAccessAlarm } from '@aws-amplify/ui-react';` → `import { MdAccessAlarm } from 'react-icons/md';`
+ */
 export const IconAccessAlarm = (props) => {
   const { className, ...rest } = props;
+  useDeprecationWarning({
+    shouldWarn: true,
+    message: `Built-in icons are being deprecated in the next major release. You can use the react-icons (https://react-icons.github.io/react-icons) package with the Material Icon set in place of these icons or any other React Icon library.
+import { IconAccessAlarm } from '@aws-amplify/ui-react'; → import { MdAccessAlarm } from 'react-icons/md';`,
+  });
   return (
     <View
       as="span"