refactor(live-region): update live region helpers to match ADR

.changeset/five-humans-retire.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Add experimental support for the AriaStatus, AriaAlert, and Announce components

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

@@ -2,8 +2,7 @@ import {Banner} from '../Banner'
 import {action} from '@storybook/addon-actions'
 import Link from '../Link'
 import type {Meta} from '@storybook/react'
-import {Status} from '../internal/components/Status'
-import {Alert} from '../internal/components/Alert'
+import {AriaAlert, AriaStatus} from '../live-region'
 import FormControl from '../FormControl'
 import RadioGroup from '../RadioGroup'
 import Radio from '../Radio'
@@ -30,7 +29,7 @@ export const WithUserAction = () => {
  <Banner
  ref={bannerRef}
  title="Error"
- description={<Alert>Something went wrong. Please try again later.</Alert>}
+ description={<AriaAlert>Something went wrong. Please try again later.</AriaAlert>}
  variant="critical"
  />
  ) : null}
@@ -60,7 +59,7 @@ export const WithDynamicContent = () => {
  <>
  <Banner
  title="Info"
- description={<Status>{messages.get(selected)}</Status>}
+ description={<AriaStatus>{messages.get(selected)}</AriaStatus>}
  onDismiss={action('onDismiss')}
  primaryAction={<Banner.PrimaryAction>Button</Banner.PrimaryAction>}
  secondaryAction={<Banner.SecondaryAction>Button</Banner.SecondaryAction>}

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

@@ -3,7 +3,7 @@ import type {Meta} from '@storybook/react'
 import Spinner from './Spinner'
 import {Box, Button} from '..'
 import {VisuallyHidden} from '../internal/components/VisuallyHidden'
-import {Status} from '../internal/components/Status'
+import {AriaStatus} from '../live-region'
 
 export default {
  title: 'Components/Spinner/Examples',
@@ -47,7 +47,7 @@ export const FullLifecycle = () => {
  {state === 'loading' && <Spinner />}
  <p>{loadedContent}</p>
  <VisuallyHidden>
- <Status>{state === 'done' && 'Content finished loading'}</Status>
+ <AriaStatus>{state === 'done' && 'Content finished loading'}</AriaStatus>
  </VisuallyHidden>
  </>
  )
@@ -84,12 +84,12 @@ export const FullLifecycleVisibleLoadingText = () => {
  {state !== 'done' && (
  <Box sx={{alignItems: 'center', display: 'flex', gap: '0.25rem'}}>
  {state === 'loading' && <Spinner size="small" srText={null} />}
- <Status>{state === 'loading' ? 'Content is loading...' : ''}</Status>
+ <AriaStatus>{state === 'loading' ? 'Content is loading...' : ''}</AriaStatus>
  </Box>
  )}
  <p>{loadedContent}</p>
  <VisuallyHidden>
- <Status>{state === 'done' && 'Content finished loading'}</Status>
+ <AriaStatus>{state === 'done' && 'Content finished loading'}</AriaStatus>
  </VisuallyHidden>
  </Box>
  )

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

@@ -2,7 +2,7 @@ import React from 'react'
 import type {Meta} from '@storybook/react'
 import Spinner from './Spinner'
 import {Box} from '..'
-import {Status} from '../internal/components/Status'
+import {AriaStatus} from '../live-region'
 
 export default {
  title: 'Components/Spinner/Features',
@@ -16,6 +16,6 @@ export const Large = () => <Spinner size="large" />
 export const SuppressScreenReaderText = () => (
  <Box sx={{alignItems: 'center', display: 'flex', gap: '0.25rem'}}>
  <Spinner size="small" srText={null} />
- <Status>Loading...</Status>
+ <AriaStatus>Loading...</AriaStatus>
  </Box>
 )

packages/react/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -242,6 +242,12 @@ exports[`@primer/react/drafts should not update exports without a semver change
 [
  "ActionBar",
  "type ActionBarProps",
+ "Announce",
+ "type AnnounceProps",
+ "AriaAlert",
+ "type AriaAlertProps",
+ "AriaStatus",
+ "type AriaStatusProps",
  "Banner",
  "type BannerProps",
  "Blankslate",
@@ -347,6 +353,12 @@ exports[`@primer/react/experimental should not update exports without a semver c
 [
  "ActionBar",
  "type ActionBarProps",
+ "Announce",
+ "type AnnounceProps",
+ "AriaAlert",
+ "type AriaAlertProps",
+ "AriaStatus",
+ "type AriaStatusProps",
  "Banner",
  "type BannerProps",
  "Blankslate",

packages/react/src/drafts/SelectPanel2/SelectPanel.tsx

@@ -23,7 +23,7 @@ import type {OverlayProps} from '../../Overlay/Overlay'
 import {StyledOverlay, heightMap} from '../../Overlay/Overlay'
 import InputLabel from '../../internal/components/InputLabel'
 import {invariant} from '../../utils/invariant'
-import {Status} from '../../internal/components/Status'
+import {AriaStatus} from '../../live-region'
 import {useResponsiveValue} from '../../hooks/useResponsiveValue'
 import type {ResponsiveValue} from '../../hooks/useResponsiveValue'
 
@@ -604,7 +604,8 @@ const SelectPanelSecondaryAction: React.FC<SelectPanelSecondaryActionProps> = ({
 
 const SelectPanelLoading = ({children = 'Fetching items...'}: React.PropsWithChildren) => {
  return (
- <Status
+ <AriaStatus
+ announceOnShow
  sx={{
  display: 'flex',
  flexDirection: 'column',
@@ -618,7 +619,7 @@ const SelectPanelLoading = ({children = 'Fetching items...'}: React.PropsWithChi
  >
  <Spinner size="medium" srText={null} />
  <Text sx={{fontSize: 1, color: 'fg.muted'}}>{children}</Text>
- </Status>
+ </AriaStatus>
  )
 }
 

packages/react/src/drafts/index.ts

@@ -75,6 +75,9 @@ export * from '../ActionBar'
 export {Stack} from '../Stack'
 export type {StackProps, StackItemProps} from '../Stack'
 
+export {Announce, AriaStatus, AriaAlert} from '../live-region'
+export type {AnnounceProps, AriaStatusProps, AriaAlertProps} from '../live-region'
+
 export * from './UnderlinePanels'
 
 export {SkeletonBox, SkeletonText, SkeletonAvatar} from './Skeleton'

packages/react/src/internal/hooks/useEffectCallback.ts

@@ -0,0 +1,20 @@
+import {useCallback, useEffect, useRef} from 'react'
+
+/**
+ * Create a callback that can be used within an effect without re-running the
+ * effect when the values used change. The callback passed to this hook will
+ * always see the latest snapshot of values that it uses and does not need to
+ * use a dependency array.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useEffectCallback<T extends (...args: any) => any>(callback: T) {
+ const savedCallback = useRef<T>(callback)
+
+ useEffect(() => {
+ savedCallback.current = callback
+ }, [callback])
+
+ return useCallback((...args: Parameters<T>): ReturnType<T> => {
+ return savedCallback.current(...args)
+ }, [])
+}

packages/react/src/internal/components/Status.stories.tsx → packages/react/src/live-region/Announce.features.stories.tsx

@@ -1,26 +1,11 @@
 import type {StoryObj} from '@storybook/react'
 import React, {useEffect, useState} from 'react'
-import {Status} from './Status'
-import {VisuallyHidden} from './VisuallyHidden'
+import {Announce} from './Announce'
+import {VisuallyHidden} from '../internal/components/VisuallyHidden'
 
 export default {
- title: 'Private/Components/Status',
- component: Status,
-}
-
-export const Default = () => {
- const [message, setMessage] = useState('Default message')
-
- useEffect(() => {
- const interval = setInterval(() => {
- setMessage(`Last updated at ${new Date().toLocaleTimeString()}`)
- }, 5000)
- return () => {
- clearInterval(interval)
- }
- }, [])
-
- return <Status>{message}</Status>
+ title: 'Drafts/Components/Announce/Features',
+ component: Announce,
 }
 
 export const VisuallyHiddenStory: StoryObj = {
@@ -30,9 +15,24 @@ export const VisuallyHiddenStory: StoryObj = {
  <>
  <p>This is an example</p>
  <VisuallyHidden>
- <Status>A visually hidden message</Status>
+ <Announce>A visually hidden message</Announce>
  </VisuallyHidden>
  </>
  )
  },
 }
+
+export const WithDelay = () => {
+ const [message, setMessage] = useState('Default message')
+
+ useEffect(() => {
+ const interval = setInterval(() => {
+ setMessage(`Last updated at ${new Date().toLocaleTimeString()}`)
+ }, 5000)
+ return () => {
+ clearInterval(interval)
+ }
+ }, [])
+
+ return <Announce delayMs={1000}>{message}</Announce>
+}