ButtonLink: new component forked from Button (#3093)

docs/docs-components/data/components.js

@@ -20,6 +20,7 @@ import AvatarGroup from '../../graphics/general/AvatarGroup.svg';
 import Badge from '../../graphics/general/Badge.svg';
 import Button from '../../graphics/general/Button.svg';
 import ButtonGroup from '../../graphics/general/ButtonGroup.svg';
+import ButtonLink from '../../graphics/general/ButtonLink.svg';
 import Callout from '../../graphics/general/Callout.svg';
 import Checkbox from '../../graphics/general/Checkbox.svg';
 import Collage from '../../graphics/general/Collage.svg';
@@ -383,6 +384,32 @@ const componentData: $ReadOnlyArray<ComponentData> = [
       },
     },
   },
+  {
+    id: 'ButtonLink',
+    platform: {
+      web: {
+        name: 'ButtonLink',
+        visual: {
+          svg: <ButtonLink />,
+        },
+        description: 'ButtonLink allow users to use a surface action to link to another page.',
+        category: ['Actions'],
+        status: {
+          accessible: {
+            summary: 'ready',
+            a11yVisual: 'ready',
+            a11yScreenreader: 'ready',
+            a11yNavigation: 'ready',
+            a11yComprehension: 'ready',
+          },
+          documentation: 'ready',
+          figmaStatus: 'notAvailable',
+          responsive: 'ready',
+          status: 'ready',
+        },
+      },
+    },
+  },
   {
     id: 'ButtonGroup',
     platform: {

docs/docs-components/siteIndex.js

@@ -110,6 +110,7 @@ const siteIndex: $ReadOnlyArray<siteIndexType> = [
       'Badge',
       'Box',
       'Button',
+      'ButtonLink',
       'ButtonGroup',
       'Callout',
       'Checkbox',

docs/examples/button/roleLinkExample.js → docs/examples/buttonlink/main.js

@@ -1,16 +1,16 @@
 // @flow strict
 import { type Node } from 'react';
-import { Button, Flex } from 'gestalt';
+import { ButtonLink, Flex } from 'gestalt';
 
 export default function Example(): Node {
   return (
     <Flex alignItems="center" height="100%" justifyContent="center" width="100%">
-      <Button
+      <ButtonLink
         accessibilityLabel="Visit Pinterest"
         iconEnd="visit"
         size="lg"
+        color="red"
         text="Visit Pinterest"
-        role="link"
         href="https://pinterest.com"
       />
     </Flex>

docs/examples/button/relAndTargetExample.js → docs/examples/buttonlink/relAndTargetExample.js

@@ -1,16 +1,15 @@
 // @flow strict
 import { type Node } from 'react';
-import { Button, Flex } from 'gestalt';
+import { ButtonLink, Flex } from 'gestalt';
 
 export default function Example(): Node {
   return (
     <Flex alignItems="center" height="100%" justifyContent="center" width="100%">
-      <Button
+      <ButtonLink
         accessibilityLabel="Visit Pinterest"
         iconEnd="visit"
         size="lg"
         text="Visit Pinterest"
-        role="link"
         rel="nofollow"
         target="blank"
         href="#"

docs/pages/visual-test/ButtonLink-dark.js

@@ -0,0 +1,22 @@
+// @flow strict
+import { type Node } from 'react';
+import { Box, ButtonLink, ColorSchemeProvider } from 'gestalt';
+
+export default function Snapshot(): Node {
+  return (
+    <ColorSchemeProvider colorScheme="dark">
+      <Box color="default" display="inlineBlock" padding={1}>
+        <ButtonLink
+          accessibilityLabel="Visit Pinterest"
+          iconEnd="visit"
+          size="lg"
+          color="red"
+          text="Visit Pinterest"
+          rel="nofollow"
+          target="blank"
+          href="#"
+        />
+      </Box>
+    </ColorSchemeProvider>
+  );
+}

docs/pages/visual-test/ButtonLink.js

@@ -0,0 +1,20 @@
+// @flow strict
+import { type Node } from 'react';
+import { Box, ButtonLink } from 'gestalt';
+
+export default function Snapshot(): Node {
+  return (
+    <Box padding={1}>
+      <ButtonLink
+        accessibilityLabel="Visit Pinterest"
+        iconEnd="visit"
+        size="lg"
+        color="red"
+        text="Visit Pinterest"
+        rel="nofollow"
+        target="blank"
+        href="#"
+      />
+    </Box>
+  );
+}

docs/pages/web/button.js

@@ -1,6 +1,6 @@
 // @flow strict
 import { type Node } from 'react';
-import { Button, SlimBanner } from 'gestalt';
+import { Button, Link, SlimBanner, Text } from 'gestalt';
 import AccessibilitySection from '../../docs-components/AccessibilitySection.js';
 import CombinationNew from '../../docs-components/CombinationNew.js';
 import docGen, { type DocGen, type DocType } from '../../docs-components/docgen.js';
@@ -22,9 +22,7 @@ import keepSimpleTextDont from '../../examples/button/keepSimpleTextDont.js';
 import main from '../../examples/button/main.js';
 import placePrimaryButtonDo from '../../examples/button/placePrimaryButtonDo.js';
 import placePrimaryButtonDont from '../../examples/button/placePrimaryButtonDont.js';
-import relAndTargetExample from '../../examples/button/relAndTargetExample.js';
 import roleButtonExample from '../../examples/button/roleButtonExample.js';
-import roleLinkExample from '../../examples/button/roleLinkExample.js';
 import selectedStateExample from '../../examples/button/selectedStateExample.js';
 import showFullTextDo from '../../examples/button/showFullTextDo.js';
 import showFullTextDont from '../../examples/button/showFullTextDont.js';
@@ -34,6 +32,22 @@ const PREVIEW_HEIGHT = 300;
 export default function DocsPage({ generatedDocGen }: DocType): Node {
   return (
     <Page title={generatedDocGen?.displayName}>
+      <SlimBanner
+        type="info"
+        message={
+          <Text inline>
+            If you intend to use Button as a link, use
+            <Link
+              accessibilityLabel="Learn more about the ButtonLink component."
+              display="inline"
+              href="/web/ButtonLink"
+            >
+              ButtonLink
+            </Link>
+            instead.
+          </Text>
+        }
+      />
       <PageHeader name={generatedDocGen?.displayName} description={generatedDocGen?.description}>
         <SandpackExample code={main} name="Main Button example" hideEditor previewHeight={150} />
       </PageHeader>
@@ -165,7 +179,10 @@ export default function DocsPage({ generatedDocGen }: DocType): Node {
             name: 'href',
             type: 'string',
             required: false,
-            description: ['Specifies a link URL. Required with `role="link"` Buttons.'],
+            description: [
+              'Specifies a link URL. Required with `role="link"` Buttons.',
+              '*This option is deprecated, use [ButtonLink](/web/ButtonLink) instead.*',
+            ],
           },
           {
             name: 'ref',
@@ -187,14 +204,20 @@ export default function DocsPage({ generatedDocGen }: DocType): Node {
             type: `'button' | 'link'`,
             required: false,
             defaultValue: 'button',
-            description: ['Use “link” to indicate Button that is acting as an `<a>` link.'],
+            description: [
+              'Use “link” to indicate Button that is acting as an `<a>` link.',
+              '*This option is deprecated, use [ButtonLink](/web/ButtonLink) instead.*',
+            ],
           },
           {
             name: 'rel',
             type: `'none' | 'nofollow'`,
             required: false,
             defaultValue: 'none',
-            description: 'Optional with link-role Buttons.',
+            description: [
+              'Optional with link-role Buttons.',
+              '*This option is deprecated, use [ButtonLink](/web/ButtonLink) instead.*',
+            ],
           },
           {
             name: 'target',
@@ -203,6 +226,7 @@ export default function DocsPage({ generatedDocGen }: DocType): Node {
             defaultValue: 'null',
             description: [
               'Indicates the browsing context where an href will be opened. Optional with `role="link"` Buttons.',
+              '*This option is deprecated, use [ButtonLink](/web/ButtonLink) instead.*',
             ],
           },
         ]}
@@ -510,35 +534,6 @@ If Button is used as a control Button to show/hide a Popover-based component, we
               <SandpackExample code={roleButtonExample} name="Role button example." />
             }
           />
-          <MainSection.Card
-            cardSize="md"
-            sandpackExample={<SandpackExample code={roleLinkExample} name="Role link example." />}
-          />
-        </MainSection.Subsection>
-
-        <MainSection.Subsection
-          title="rel and target"
-          description={`
-These optional props control the behavior of \`role="link"\` Buttons. External links commonly use \`target="_blank"\` to open the link in a new tab or window, and \`rel="nofollow"\` to provide hints for SEO.
-`}
-        >
-          <SlimBanner
-            iconAccessibilityLabel="Localize the default label"
-            message="Button with link role announces to assistive technologies that the link opens in a new tab. Localize the default label with DefaultLabelProvider."
-            type="recommendationBare"
-            helperLink={{
-              text: 'Learn more',
-              accessibilityLabel: 'Learn more about DefaultLabelProvider',
-              href: '/web/utilities/defaultlabelprovider',
-              onClick: () => {},
-            }}
-          />
-          <MainSection.Card
-            cardSize="lg"
-            sandpackExample={
-              <SandpackExample code={relAndTargetExample} name="Rel and target example." />
-            }
-          />
         </MainSection.Subsection>
 
         <MainSection.Subsection
@@ -636,6 +631,9 @@ To control focus or position anchored components relative to Button, use \`ref\`
       <MainSection name="Related">
         <MainSection.Subsection
           description={`
+**[ButtonLink](/web/buttonlink)**
+Use ButtonLink when a link is needed instead of an action.
+
 **[ButtonGroup](/web/buttongroup)**
 When displaying multiple Buttons in a layout, use ButtonGroup to ensure consistent spacing and wrapping behavior.