fix: announce webhook content changes to screen readers on every action type switch (#61852)

Co-authored-by: docs-bot <77750099+docs-bot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

data/ui.yml

@@ -293,6 +293,7 @@ secret_scanning:
 webhooks:
   action_type_switch_error: There was an error switching webhook action types.
   action_type: Action type
+  action_type_selected: "'{{ actionType }}' action selected. {{ description }}"
   availability: Availability for <code>{{ WebhookName }}</code>
   webhook_payload_object: Webhook payload object for <code>{{ WebhookName }}</code>
   webhook_payload_example: Webhook payload example

src/fixtures/fixtures/data/ui.yml

@@ -293,6 +293,7 @@ secret_scanning:
 webhooks:
   action_type_switch_error: There was an error switching webhook action types.
   action_type: Action type
+  action_type_selected: "'{{ actionType }}' action selected. {{ description }}"
   availability: Availability for <code>{{ WebhookName }}</code>
   webhook_payload_object: Webhook payload object for <code>{{ WebhookName }}</code>
   webhook_payload_example: Webhook payload example

src/webhooks/components/Webhook.tsx

@@ -1,7 +1,6 @@
 import { ActionList, ActionMenu, Flash } from '@primer/react'
-import { useState, useEffect } from 'react'
+import { useState, useEffect, useCallback } from 'react'
 import useSWR from 'swr'
-import { useRouter } from 'next/router'
 import { slug } from 'github-slugger'
 import cx from 'classnames'
 import { announce } from '@primer/live-region-element'
@@ -33,7 +32,6 @@ export function Webhook({ webhook }: Props) {
   // Get version for requests to switch webhook action type
   const version = useVersion()
   const { t, tObject } = useTranslation('webhooks')
-  const router = useRouter()
 
   // Get more user friendly language for the different availability options in
   // the webhook schema (we can't change it directly in the schema).  Note that
@@ -48,13 +46,28 @@ export function Webhook({ webhook }: Props) {
   // The index of the selected action type so we can highlight which one is selected
   // in the action type dropdown
   const [selectedActionTypeIndex, setSelectedActionTypeIndex] = useState(0)
+  // Tracks whether we need to announce once data loads (first interaction only,
+  // before SWR cache is populated).
+  const [pendingAnnouncement, setPendingAnnouncement] = useState('')
 
   const webhookSlug = slug(webhook.data.category)
   const webhookFetchUrl = `/api/webhooks/v1?${new URLSearchParams({
     category: webhook.data.category,
     version: version.currentVersion,
   })}`
 
+  // fires when the webhook action type changes or someone clicks on a nested
+  // body param for the first time.  In either case, we now have all the data
+  // for a webhook (i.e. all the data for each action type and all of their
+  // nested parameters)
+  const { data, error } = useSWR<WebhookData, Error>(
+    clickedBodyParameterName || selectedWebhookActionType ? webhookFetchUrl : null,
+    webhookFetcher,
+    {
+      revalidateOnFocus: false,
+    },
+  )
+
   // When you load the page we want to support linking to a specific webhook type
   // so this effect sets the webhook type if it's provided in the URL e.g.:
   //
@@ -72,6 +85,20 @@ export function Webhook({ webhook }: Props) {
     }
   }, [])
 
+  // Build a plain-text announcement from the webhook action data.
+  const buildAnnouncement = useCallback(
+    (type: string, actionData: { descriptionHtml: string }) => {
+      const tempEl = document.createElement('div')
+      tempEl.innerHTML = actionData.descriptionHtml
+      const description = tempEl.textContent?.trim() || ''
+      return t('action_type_selected')
+        .replace('{{ actionType }}', type)
+        .replace('{{ description }}', description)
+        .trim()
+    },
+    [t],
+  )
+
   // callback for the action type dropdown -- sets the action type to the given
   // type, index is the index of the selected type so we can highlight it as
   // selected.
@@ -86,48 +113,49 @@ export function Webhook({ webhook }: Props) {
     setSelectedWebhookActionType(type)
     setSelectedActionTypeIndex(index)
 
-    // Announce the newly selected action type to screen readers so users
-    // relying on AT know the page content has changed.
-    announce(`${t('action_type')}: ${type}`, { politeness: 'polite' })
-
-    const { asPath, locale } = router
-    let [pathRoot, pathQuery = ''] = asPath.split('?')
-    const params = new URLSearchParams(pathQuery)
-
-    if (pathRoot.includes('#')) {
-      pathRoot = pathRoot.split('#')[0]
+    // If SWR data is already cached, announce immediately. Otherwise, flag
+    // the type so the effect can announce once data arrives.
+    if (data && data[type]) {
+      // Use setTimeout so the announcement fires after the ActionMenu closes
+      // and VoiceOver finishes reading the button. Compute message eagerly to
+      // avoid stale closures if data changes before the timeout fires.
+      const message = buildAnnouncement(type, data[type])
+      setTimeout(() => {
+        announce(message, { politeness: 'assertive' })
+      }, 150)
+    } else {
+      setPendingAnnouncement(type)
     }
 
-    params.set('actionType', type)
-    router.push(
-      { pathname: `/${locale}${pathRoot}`, query: params.toString(), hash: webhookSlug },
-      undefined,
-      {
-        shallow: true,
-      },
-    )
+    // Update the URL without triggering Next.js router navigation, which causes
+    // VoiceOver to re-read the page title and swallow live-region announcements.
+    const url = new URL(location.href)
+    url.searchParams.set('actionType', type)
+    url.hash = webhookSlug
+    window.history.replaceState(window.history.state, '', url.toString())
   }
 
   // callback to trigger useSWR() hook after a nested property is clicked
   function handleBodyParamExpansion(target: HTMLDetailsElement) {
     setClickedBodyParameterName(target.closest('details')?.dataset.nestedParamId)
   }
 
-  // fires when the webhook action type changes or someone clicks on a nested
-  // body param for the first time.  In either case, we now have all the data
-  // for a webhook (i.e. all the data for each action type and all of their
-  // nested parameters)
-  const { data, error } = useSWR<WebhookData, Error>(
-    clickedBodyParameterName || selectedWebhookActionType ? webhookFetchUrl : null,
-    webhookFetcher,
-    {
-      revalidateOnFocus: false,
-    },
-  )
-
   const currentWebhookActionType = selectedWebhookActionType || webhook.data.action
   const currentWebhookAction = (data && data[currentWebhookActionType]) || webhook.data
 
+  // Announce content changes when data arrives for the first time (before SWR
+  // cache is populated). Subsequent changes are announced directly in the handler.
+  useEffect(() => {
+    if (!pendingAnnouncement || !data || !data[pendingAnnouncement]) return
+    const type = pendingAnnouncement
+    setPendingAnnouncement('')
+
+    const message = buildAnnouncement(type, data[type])
+    setTimeout(() => {
+      announce(message, { politeness: 'assertive' })
+    }, 150)
+  }, [data, pendingAnnouncement, buildAnnouncement])
+
   return (
     <div>
       <HeadingLink as="h2" slug={webhookSlug}>