feat(a11y): add reusable header ID plumbing for Prompt, Alert, and Viewer primitives

MartinCupela · MartinCupela · commit cc4b6b5a120d · 2026-04-27T14:01:22.000+02:00
diff --git a/examples/vite/src/CustomMessageActions/ConfigurableMessageActions.tsx b/examples/vite/src/CustomMessageActions/ConfigurableMessageActions.tsx
@@ -1,4 +1,11 @@
-import { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
 import type { DeleteMessageOptions, LocalMessage } from 'stream-chat';
 import {
   Alert,
@@ -281,6 +288,7 @@ export const ConfigurableMessageActions = (
   const { customMessageActions } = useAppSettingsSelector(
     (state) => state.messageActions,
   );
+  const customDeleteEnabled = customMessageActions.delete.enableOptionConfiguration;
   const configurableActionSet = useMemo(() => {
     const actionSet = props.messageActionSet ?? defaultMessageActionSet;
     const actionOverrides: Record<
@@ -309,7 +317,7 @@ export const ConfigurableMessageActions = (
     const overrides: CustomMessageActionOverrideSpec[] = [
       {
         ...actionOverrides.delete,
-        enabled: true,
+        enabled: customDeleteEnabled,
       },
       {
         ...actionOverrides.markOwnUnread,
@@ -318,21 +326,27 @@ export const ConfigurableMessageActions = (
     ];
 
     return applyCustomMessageActionOverrides({ messageActionSet: actionSet, overrides });
-  }, [customMessageActions, props.messageActionSet]);
+  }, [customDeleteEnabled, customMessageActions.markOwnUnread, props.messageActionSet]);
   const openDeleteDialog = useCallback((params: OpenDeleteDialogParams) => {
     setDeleteDialogTarget(params);
   }, []);
 
+  useEffect(() => {
+    if (!customDeleteEnabled && deleteDialogTarget) {
+      setDeleteDialogTarget(null);
+    }
+  }, [customDeleteEnabled, deleteDialogTarget]);
+
   return (
     <CustomDeleteActionContext.Provider value={{ openDeleteDialog }}>
       <MessageActions {...props} messageActionSet={configurableActionSet} />
       <Modal
-        open={Boolean(deleteDialogTarget)}
+        open={customDeleteEnabled && Boolean(deleteDialogTarget)}
         onClose={() => {
           setDeleteDialogTarget(null);
         }}
       >
-        {deleteDialogTarget && (
+        {customDeleteEnabled && deleteDialogTarget && (
           <CustomDeleteMessageAlert
             enableOptionConfiguration={
               customMessageActions.delete.enableOptionConfiguration
diff --git a/src/components/Dialog/components/Alert.tsx b/src/components/Dialog/components/Alert.tsx
@@ -1,5 +1,7 @@
 import React, { type ComponentProps, type ComponentType, forwardRef } from 'react';
 import clsx from 'clsx';
+import { useModalContext } from '../../../context';
+import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
 
 export const Root = forwardRef<HTMLDivElement, ComponentProps<'div'>>(function AlertRoot(
   { children, className, ...props }: ComponentProps<'div'>,
@@ -13,24 +15,39 @@ export const Root = forwardRef<HTMLDivElement, ComponentProps<'div'>>(function A
 });
 
 export type AlertHeaderProps = ComponentProps<'div'> & {
-  title?: string;
   description?: string;
+  descriptionId?: string;
   Icon?: ComponentType;
+  title?: string;
+  titleId?: string;
 };
 
 export const Header = forwardRef<HTMLDivElement, AlertHeaderProps>(function AlertHeader(
-  { children, className, description, Icon, title, ...props },
+  { children, className, description, descriptionId, Icon, title, titleId, ...props },
   ref,
 ) {
+  const { dialogId } = useModalContext();
+  const { descriptionId: derivedDescriptionId, titleId: derivedTitleId } =
+    useAriaIdentifiers(dialogId);
+  const resolvedTitleId = titleId ?? derivedTitleId;
+  const resolvedDescriptionId = descriptionId ?? derivedDescriptionId;
+
   return (
     <div {...props} className={clsx('str-chat__alert-header', className)} ref={ref}>
       {title ? (
         <>
           {Icon && <Icon />}
           <div className='str-chat__alert-header__copy'>
-            <div className='str-chat__alert-header__title'>{title}</div>
+            <h2 className='str-chat__alert-header__title' id={resolvedTitleId}>
+              {title}
+            </h2>
             {description && (
-              <div className='str-chat__alert-header__description'>{description}</div>
+              <p
+                className='str-chat__alert-header__description'
+                id={resolvedDescriptionId}
+              >
+                {description}
+              </p>
             )}
           </div>
         </>
diff --git a/src/components/Dialog/components/Prompt.tsx b/src/components/Dialog/components/Prompt.tsx
@@ -2,7 +2,8 @@ import React, { type ComponentProps, type PropsWithChildren } from 'react';
 import clsx from 'clsx';
 import { Button, type ButtonProps } from '../../Button';
 import { IconXmark } from '../../Icons';
-import { useTranslationContext } from '../../../context';
+import { useModalContext, useTranslationContext } from '../../../context';
+import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
 
 const PromptRoot = ({ children, className, ...props }: ComponentProps<'div'>) => (
   <div {...props} className={clsx('str-chat__prompt', className)}>
@@ -15,17 +16,35 @@ export type PromptHeaderProps = {
   description?: string;
   className?: string;
   close?: () => void;
+  descriptionId?: string;
+  titleId?: string;
 };
 
-const PromptHeader = ({ className, close, description, title }: PromptHeaderProps) => {
+const PromptHeader = ({
+  className,
+  close,
+  description,
+  descriptionId,
+  title,
+  titleId,
+}: PromptHeaderProps) => {
   const { t } = useTranslationContext();
+  const { dialogId } = useModalContext();
+  const { descriptionId: derivedDescriptionId, titleId: derivedTitleId } =
+    useAriaIdentifiers(dialogId);
+  const resolvedTitleId = titleId ?? derivedTitleId;
+  const resolvedDescriptionId = descriptionId ?? derivedDescriptionId;
 
   return (
     <div className={clsx('str-chat__prompt__header', className)}>
       <div className='str-chat__prompt__header__title-group'>
-        <div className='str-chat__prompt__header__title'>{title}</div>
+        <h2 className='str-chat__prompt__header__title' id={resolvedTitleId}>
+          {title}
+        </h2>
         {description != null && description !== '' && (
-          <div className='str-chat__prompt__header__description'>{description}</div>
+          <p className='str-chat__prompt__header__description' id={resolvedDescriptionId}>
+            {description}
+          </p>
         )}
       </div>
       {close && (
diff --git a/src/components/Dialog/components/Viewer.tsx b/src/components/Dialog/components/Viewer.tsx
@@ -2,7 +2,8 @@ import React, { type ComponentProps, type PropsWithChildren } from 'react';
 import clsx from 'clsx';
 import { Button, type ButtonProps } from '../../Button';
 import { IconArrowLeft, IconXmark } from '../../Icons';
-import { useTranslationContext } from '../../../context';
+import { useModalContext, useTranslationContext } from '../../../context';
+import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
 
 const ViewerRoot = ({ children, className, ...props }: ComponentProps<'div'>) => (
   <div {...props} className={clsx('str-chat__viewer', className)}>
@@ -16,16 +17,25 @@ export type ViewerHeaderProps = {
   className?: string;
   close?: () => void;
   goBack?: () => void;
+  descriptionId?: string;
+  titleId?: string;
 };
 
 const ViewerHeader = ({
   className,
   close,
   description,
+  descriptionId,
   goBack,
   title,
+  titleId,
 }: ViewerHeaderProps) => {
   const { t } = useTranslationContext();
+  const { dialogId } = useModalContext();
+  const { descriptionId: derivedDescriptionId, titleId: derivedTitleId } =
+    useAriaIdentifiers(dialogId);
+  const resolvedTitleId = titleId ?? derivedTitleId;
+  const resolvedDescriptionId = descriptionId ?? derivedDescriptionId;
 
   return (
     <div className={clsx('str-chat__viewer__header', className)}>
@@ -43,9 +53,13 @@ const ViewerHeader = ({
         </Button>
       )}
       <div className='str-chat__viewer__header__title-group'>
-        <div className='str-chat__viewer__header__title'>{title}</div>
+        <h2 className='str-chat__viewer__header__title' id={resolvedTitleId}>
+          {title}
+        </h2>
         {description != null && description !== '' && (
-          <div className='str-chat__viewer__header__description'>{description}</div>
+          <p className='str-chat__viewer__header__description' id={resolvedDescriptionId}>
+            {description}
+          </p>
         )}
       </div>
       {close && (
diff --git a/src/components/MessageActions/DeleteMessageAlert.tsx b/src/components/MessageActions/DeleteMessageAlert.tsx
@@ -11,6 +11,7 @@ export type DeleteMessageAlertProps = {
 export const DeleteMessageAlert = ({ onCancel, onDelete }: DeleteMessageAlertProps) => {
   const { t } = useTranslationContext();
   const { close } = useModalContext();
+
   return (
     <Alert.Root
       className='str-chat__delete-message-alert'
@@ -33,6 +34,7 @@ export const DeleteMessageAlert = ({ onCancel, onDelete }: DeleteMessageAlertPro
         </Button>
         <Button
           appearance='outline'
+          autoFocus
           className='str-chat__delete-message-alert__cancel-button'
           data-testid='delete-message-alert-cancel-button'
           onClick={() => {
diff --git a/src/components/MessageActions/MessageActions.defaults.tsx b/src/components/MessageActions/MessageActions.defaults.tsx
@@ -678,7 +678,7 @@ const DefaultMessageActionComponents = {
           >
             {t('Delete message')}
           </MessageActionsMenuItemButton>
-          <Modal open={openModal}>
+          <Modal open={openModal} role='alertdialog'>
             <DeleteMessageAlert
               onCancel={() => {
                 setOpenModal(false);
diff --git a/src/components/MessageActions/__tests__/MessageActions.test.tsx b/src/components/MessageActions/__tests__/MessageActions.test.tsx
@@ -329,6 +329,28 @@ describe('<MessageActions />', () => {
       expect(screen.queryByText('Delete message')).not.toBeInTheDocument();
     });
 
+    it('should render delete confirmation as labeled alertdialog with description', async () => {
+      const message = generateMessage({ user: alice });
+      await renderMessageActions({
+        channelStateOpts: {
+          channelCapabilities: { 'delete-own-message': true },
+        },
+        customMessageContext: { message },
+      });
+      await toggleOpenMessageActions();
+
+      await act(async () => {
+        await fireEvent.click(screen.getByText('Delete message'));
+      });
+
+      const dialog = screen.getByRole('alertdialog', { name: 'Delete message' });
+      expect(dialog).toHaveAttribute('aria-labelledby', 'modal-dialog-title');
+      expect(dialog).toHaveAttribute('aria-describedby', 'modal-dialog-description');
+      expect(
+        screen.getByText('Are you sure you want to delete this message?'),
+      ).toHaveAttribute('id', 'modal-dialog-description');
+    });
+
     it('should include Edit in dropdown actions when user has edit capability', async () => {
       const message = generateMessage({ user: alice });
       const { container } = await renderMessageActions({
diff --git a/src/components/Modal/GlobalModal.tsx b/src/components/Modal/GlobalModal.tsx
@@ -21,6 +21,7 @@ import {
   useModalDialog,
   useModalDialogIsOpen,
 } from '../Dialog';
+import { useAriaIdentifiers } from '../../hooks/useAriaIdentifiers';
 
 export type ModalCloseEvent =
   | KeyboardEvent
@@ -40,6 +41,8 @@ export type ModalProps = {
   'aria-labelledby'?: string;
   /** ID of the element that describes the modal dialog. */
   'aria-describedby'?: string;
+  /** ARIA role for the modal dialog surface. */
+  role?: 'alertdialog' | 'dialog';
   /** If provided, the close button is rendered on overlay */
   CloseButtonOnOverlay?: ComponentType<ComponentProps<'button'>>;
   /** Callback handler for closing of modal. */
@@ -58,13 +61,27 @@ export const GlobalModal = ({
   onClose,
   onCloseAttempt,
   open,
+  role = 'dialog',
 }: PropsWithChildren<ModalProps>) => {
   const dialog = useModalDialog();
   const isOpen = useModalDialogIsOpen();
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const closeButtonRef = useRef<HTMLButtonElement | null>(null);
   const closingRef = useRef(false);
-  const { theme } = useChatContext('GlobalModal');
+  const { theme } = useChatContext();
+  const dialogLabelingBaseId = dialog.id;
+  const {
+    descriptionId: derivedAriaDescribedby = ariaDescribedby,
+    titleId: derivedAriaLabelledby = ariaLabelledby,
+  } = useAriaIdentifiers(dialogLabelingBaseId);
+  const resolvedAriaLabelledby = ariaLabel
+    ? ariaLabelledby
+    : (ariaLabelledby ?? derivedAriaLabelledby);
+  const resolvedAriaDescribedby =
+    role === 'alertdialog'
+      ? (ariaDescribedby ?? derivedAriaDescribedby)
+      : ariaDescribedby;
+  const resolvedAriaLabel = resolvedAriaLabelledby ? undefined : ariaLabel;
 
   const maybeClose = useCallback(
     (source: ModalCloseSource, event: ModalCloseEvent) => {
@@ -78,11 +95,12 @@ export const GlobalModal = ({
     [dialog, onClose, onCloseAttempt],
   );
 
-  const modalContextValue = useMemo<{ close: () => void }>(
+  const modalContextValue = useMemo<{ close: () => void; dialogId?: string }>(
     () => ({
       close: () => maybeClose('button', {} as ModalCloseEvent),
+      dialogId: dialogLabelingBaseId,
     }),
-    [maybeClose],
+    [dialogLabelingBaseId, maybeClose],
   );
 
   const handleOverlayClick = (event: React.MouseEvent<HTMLDivElement>) => {
@@ -129,13 +147,13 @@ export const GlobalModal = ({
         >
           <FocusScope autoFocus contain>
             <div
-              aria-describedby={ariaDescribedby}
-              aria-label={ariaLabelledby ? undefined : ariaLabel}
-              aria-labelledby={ariaLabelledby}
+              aria-describedby={resolvedAriaDescribedby}
+              aria-label={resolvedAriaLabel}
+              aria-labelledby={resolvedAriaLabelledby}
               aria-modal='true'
               className='str-chat__modal__dialog'
               onKeyDown={handleDialogKeyDown}
-              role='dialog'
+              role={role}
             >
               {children}
             </div>
diff --git a/src/components/Modal/__tests__/GlobalModal.test.tsx b/src/components/Modal/__tests__/GlobalModal.test.tsx
diff --git a/src/context/ModalContext.tsx b/src/context/ModalContext.tsx

Original file line number	Diff line number	Diff line change
`@@ -678,7 +678,7 @@ const DefaultMessageActionComponents = {`
`678`	`678`	`>`
`679`	`679`	`{t('Delete message')}`
`680`	`680`	`</MessageActionsMenuItemButton>`
`681`		`- <Modal open={openModal}>`
	`681`	`+ <Modal open={openModal} role='alertdialog'>`
`682`	`682`	`<DeleteMessageAlert`
`683`	`683`	`onCancel={() => {`
`684`	`684`	`setOpenModal(false);`