Add loading prop for Button and IconButton (#3582)

* draft loading state

* cleanup

* add story to trigger loading

* merge

* icon button

* Create lazy-jobs-pump.md

* add prop for loading message

* handle no visuals loading state

* updates snapshots after merging from main

* uses unique ID for loading messages, preserves aria-describedby passed to button, rms aria-busy

* adds Storybook examples for btn loading error message

* reverts unintentional default link underlining

* changes loadingMessage to loadingAnnouncement

* updates draft Button component with loading prop

* updates legacy button counter behavior when loading

* Revert "updates draft Button component with loading prop"

This reverts commit 7f7f326.

* moves error behavior stories to 'Examples' section

* screenreader fixes

* adds and updates unit tests

* re-updates snapshots after using correct VisuallyHidden

* documents loading props

* adds VRTs, updates loading feature stories

* simplifies inner visual/spinner rendering logic

* removes example stories (we can put them back when Flash supports focusing its heading)

* excludes loading buttons from axe contrast check

* fixes visual regression: button counter vertical alignment

* prevents double spinners when leading and trailing visuals are passed

* test(e2e): update story ids

* test(vrt): update snapshots

* test(e2e): disable animations in screenshots

* test(vrt): update snapshots

* preserves rest state styles when button is loading

* adds story for success and error announcement

* test(vrt): update snapshots

* fixes ButtonGroup regression

* delete broken snapshots

* also targets anchor tags in ButtonGroup styles

* add conditional wrapper

* fix group

* test(vrt): update snapshots

* lint

* fixes unit tests, updates snapshots

* Update src/Button/Button.docs.json

Co-authored-by: Pavithra Kodmad <pksjce@github.com>

* fixes 'block' layout for loading buttons

* uses new internal Status component for loading announcement

* updates Tooltip V2 tests to account for loading messageID in button's aria-describedby

* fixes BoxProps type import to new preferred syntax

* appease the linter

* rms ConditionalWrapper

* revert back to using ConditionalWrapper with aria-describedby

* test(vrt): update snapshots

---------

Co-authored-by: Mike Perrotti <mperrotti@github.com>
Co-authored-by: Josh Black <joshblack@users.noreply.github.com>
Co-authored-by: langermank <langermank@users.noreply.github.com>
Co-authored-by: Pavithra Kodmad <pksjce@github.com>
Co-authored-by: mperrotti <mperrotti@users.noreply.github.com>

.changeset/lazy-jobs-pump.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Add `loading` state to `Button` and `IconButton`

e2e/components/Button.test.ts

@@ -479,6 +479,148 @@ test.describe('Button', () => {
     }
   })
 
+  test.describe('Loading', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(`Button.Loading.${theme}.png`)
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations({
+            rules: {
+              'color-contrast': {
+                enabled: theme !== 'dark_dimmed',
+              },
+            },
+          })
+        })
+      })
+    }
+  })
+
+  test.describe('Loading Custom Announcement', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-custom-announcement',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Button.Loading Custom Announcement.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-custom-announcement',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations({
+            rules: {
+              'color-contrast': {
+                enabled: theme !== 'dark_dimmed',
+              },
+            },
+          })
+        })
+      })
+    }
+  })
+
+  test.describe('Loading With Leading Visual', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-with-leading-visual',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Button.Loading With Leading Visual.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-with-leading-visual',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations({
+            rules: {
+              'color-contrast': {
+                enabled: theme !== 'dark_dimmed',
+              },
+            },
+          })
+        })
+      })
+    }
+  })
+
+  test.describe('Loading With Trailing Visual', () => {
+    for (const theme of themes) {
+      test.describe(theme, () => {
+        test('default @vrt', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-with-trailing-visual',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+
+          // Default state
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot(
+            `Button.Loading With Trailing Visual.${theme}.png`,
+          )
+        })
+
+        test('axe @aat', async ({page}) => {
+          await visit(page, {
+            id: 'components-button-features--loading-with-trailing-visual',
+            globals: {
+              colorScheme: theme,
+            },
+          })
+          await expect(page).toHaveNoViolations({
+            rules: {
+              'color-contrast': {
+                enabled: theme !== 'dark_dimmed',
+              },
+            },
+          })
+        })
+      })
+    }
+  })
+
   test.describe('Dev: Invisible Variants', () => {
     for (const theme of themes) {
       test.describe(theme, () => {

packages/react/src/Button/Button.docs.json

@@ -18,15 +18,9 @@
       "description": "For counter buttons, the number to display."
     },
     {
-      "name": "variant",
-      "type": "'default'\n| 'primary'\n| 'danger'\n| 'invisible'",
-      "defaultValue": "'default'",
-      "description": "Change the visual style of the button."
-    },
-    {
-      "name": "size",
-      "type": "'small'\n| 'medium'\n| 'large'",
-      "defaultValue": "'medium'"
+      "name": "inactive",
+      "type": "boolean",
+      "description": "Whether the button looks visually disabled, but can still accept all the same interactions as an enabled button.\n This is intended to be used when a system error such as an outage prevents the button from performing its usual action.\n Inactive styles are slightly different from disabled styles because inactive buttons need to have an accessible color contrast ratio. This is because inactive buttons can have tooltips or perform an action such as opening a dialog explaining why it's inactive.\n If both `disabled` and `inactive` are true, `disabled` takes precedence."
     },
     {
       "name": "leadingIcon",
@@ -39,6 +33,22 @@
       "type": "React.ElementType",
       "description": "A visual to display before the button text."
     },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "description": "When true, the button is in a loading state."
+    },
+    {
+      "name": "loadingAnnouncement",
+      "type": "string",
+      "description": "The content to announce to screen readers when loading. This requires `loading` prop to be true"
+    },
+
+    {
+      "name": "size",
+      "type": "'small'\n| 'medium'\n| 'large'",
+      "defaultValue": "'medium'"
+    },
     {
       "name": "trailingIcon",
       "type": "React.ComponentType<OcticonProps>",
@@ -51,9 +61,10 @@
       "description": "A visual to display after the button text."
     },
     {
-      "name": "inactive",
-      "type": "boolean",
-      "description": "Whether the button looks visually disabled, but can still accept all the same interactions as an enabled button.\n This is intended to be used when a system error such as an outage prevents the button from performing its usual action.\n Inactive styles are slightly different from disabled styles because inactive buttons need to have an accessible color contrast ratio. This is because inactive buttons can have tooltips or perform an action such as opening a dialog explaining why it's inactive.\n If both `disabled` and `inactive` are true, `disabled` takes precedence."
+      "name": "variant",
+      "type": "'default'\n| 'primary'\n| 'danger'\n| 'invisible'",
+      "defaultValue": "'default'",
+      "description": "Change the visual style of the button."
     },
     {
       "name": "as",

packages/react/src/Button/Button.examples.stories.tsx

@@ -0,0 +1,78 @@
+import React from 'react'
+import type {Meta} from '@storybook/react'
+import {Button} from '.'
+import {DownloadIcon} from '@primer/octicons-react'
+import {VisuallyHidden} from '../internal/components/VisuallyHidden'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button/Examples',
+} as Meta<typeof Button>
+
+export default meta
+
+export const LoadingStatusAnnouncementSuccessful = () => {
+  const [loading, setLoading] = React.useState(false)
+  const [success, setSuccess] = React.useState(false)
+
+  const resolveAction = async () => {
+    setLoading(true)
+    await new Promise(resolve => setTimeout(resolve, 1500))
+    setLoading(false)
+
+    return await true
+  }
+
+  const onClick = (resolveType: 'error' | 'success') => async () => {
+    const actionResult = await resolveAction()
+
+    if (resolveType === 'error') {
+      setSuccess(!actionResult)
+      return
+    }
+
+    setSuccess(actionResult)
+  }
+
+  return (
+    <>
+      <VisuallyHidden aria-live="polite">{!loading && success ? 'Export completed' : null}</VisuallyHidden>
+      <Button loading={loading} leadingVisual={DownloadIcon} onClick={onClick('error')}>
+        Export (success)
+      </Button>
+    </>
+  )
+}
+
+export const LoadingStatusAnnouncementError = () => {
+  const [loading, setLoading] = React.useState(false)
+  const [error, setError] = React.useState(false)
+
+  const resolveAction = async () => {
+    setLoading(true)
+    await new Promise(resolve => setTimeout(resolve, 1500))
+    setLoading(false)
+
+    return await true
+  }
+
+  const onClick = (resolveType: 'error' | 'success') => async () => {
+    const actionResult = await resolveAction()
+
+    if (resolveType === 'error') {
+      setError(actionResult)
+      return
+    }
+
+    setError(!actionResult)
+  }
+
+  return (
+    <>
+      <VisuallyHidden aria-live="polite">{!loading && error ? 'Export failed' : null}</VisuallyHidden>
+
+      <Button loading={loading} leadingVisual={DownloadIcon} onClick={onClick('error')}>
+        Export (error)
+      </Button>
+    </>
+  )
+}

packages/react/src/Button/Button.features.stories.tsx

@@ -1,4 +1,4 @@
-import {EyeIcon, TriangleDownIcon, HeartIcon} from '@primer/octicons-react'
+import {EyeIcon, TriangleDownIcon, HeartIcon, DownloadIcon} from '@primer/octicons-react'
 import React, {useState} from 'react'
 import {Button} from '.'
 
@@ -96,3 +96,37 @@ export const Small = () => <Button size="small">Default</Button>
 export const Medium = () => <Button size="medium">Default</Button>
 
 export const Large = () => <Button size="large">Default</Button>
+
+export const Loading = () => <Button loading>Default</Button>
+
+export const LoadingCustomAnnouncement = () => (
+  <Button loading loadingAnnouncement="This is a custom loading announcement">
+    Default
+  </Button>
+)
+
+export const LoadingWithLeadingVisual = () => (
+  <Button loading leadingVisual={DownloadIcon}>
+    Export
+  </Button>
+)
+
+export const LoadingWithTrailingVisual = () => (
+  <Button loading trailingVisual={DownloadIcon}>
+    Export
+  </Button>
+)
+
+export const LoadingTrigger = () => {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleClick = () => {
+    setIsLoading(true)
+  }
+
+  return (
+    <Button loading={isLoading} onClick={handleClick} leadingVisual={DownloadIcon}>
+      Export
+    </Button>
+  )
+}

packages/react/src/Button/Button.stories.tsx

@@ -48,6 +48,16 @@ Playground.argTypes = {
       type: 'boolean',
     },
   },
+  loading: {
+    control: {
+      type: 'boolean',
+    },
+  },
+  count: {
+    control: {
+      type: 'number',
+    },
+  },
   leadingVisual: OcticonArgType([EyeClosedIcon, EyeIcon, SearchIcon, XIcon, HeartIcon]),
   trailingVisual: OcticonArgType([EyeClosedIcon, EyeIcon, SearchIcon, XIcon, HeartIcon]),
   trailingAction: OcticonArgType([TriangleDownIcon]),
@@ -59,6 +69,7 @@ Playground.args = {
   inactive: false,
   variant: 'default',
   alignContent: 'center',
+  loading: false,
   trailingVisual: null,
   leadingVisual: null,
   trailingAction: null,