feat(a11y): audit and apply dialog-label wiring to high-impact Prompt/Viewer call sites

Author: MartinCupela

src/a11y/hooks/useAriaIdentifiers.ts

@@ -0,0 +1,33 @@
+import { useMemo } from 'react';
+
+type AriaIdentifierDescriptor = 'description' | 'title';
+
+const sanitizeAriaRootId = (rootId?: string) =>
+  rootId?.trim().replace(/[^A-Za-z0-9:_-]/g, '-') ?? '';
+
+const buildAriaIdentifier = (
+  sanitizedRootId: string,
+  descriptor: AriaIdentifierDescriptor,
+) => (sanitizedRootId ? `${sanitizedRootId}-${descriptor}` : undefined);
+
+/**
+ * Derives stable ARIA identifier IDs from a single root ID.
+ *
+ * Use this to keep dialog/component labeling conventions consistent without
+ * manually building `*-title` and `*-description` IDs at each call site.
+ *
+ * Behavior:
+ * - Root ID is trimmed and sanitized to `[A-Za-z0-9:_-]` before use.
+ * - Returns `undefined` IDs when root ID is missing/empty after sanitization.
+ */
+export const useAriaIdentifiers = (rootId?: string) => {
+  const sanitizedRootId = sanitizeAriaRootId(rootId);
+
+  return useMemo(
+    () => ({
+      descriptionId: buildAriaIdentifier(sanitizedRootId, 'description'),
+      titleId: buildAriaIdentifier(sanitizedRootId, 'title'),
+    }),
+    [sanitizedRootId],
+  );
+};

src/a11y/hooks/useResolvedModalAriaProps.ts

@@ -0,0 +1,46 @@
+import { useMemo } from 'react';
+import { useAriaIdentifiers } from './useAriaIdentifiers';
+
+export type ResolvedModalAriaProps = {
+  'aria-describedby'?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+};
+
+type UseResolvedModalAriaPropsParams = {
+  ariaDescribedby?: string;
+  ariaLabel?: string;
+  ariaLabelledby?: string;
+  dialogId?: string;
+};
+
+/**
+ * Resolves modal labeling/description attributes from explicit props first,
+ * then from the modal dialog id convention (`${dialogId}-title|description`).
+ *
+ * Rules:
+ * - `aria-labelledby` wins over `aria-label`.
+ * - `aria-describedby` defaults to inferred id when explicit value is absent.
+ */
+export const useResolvedModalAriaProps = ({
+  ariaDescribedby,
+  ariaLabel,
+  ariaLabelledby,
+  dialogId,
+}: UseResolvedModalAriaPropsParams): ResolvedModalAriaProps => {
+  const { descriptionId, titleId } = useAriaIdentifiers(dialogId);
+
+  return useMemo(() => {
+    const resolvedAriaLabelledby = ariaLabel
+      ? ariaLabelledby
+      : (ariaLabelledby ?? titleId);
+    const resolvedAriaDescribedby = ariaDescribedby ?? descriptionId;
+    const resolvedAriaLabel = resolvedAriaLabelledby ? undefined : ariaLabel;
+
+    return {
+      'aria-describedby': resolvedAriaDescribedby,
+      'aria-label': resolvedAriaLabel,
+      'aria-labelledby': resolvedAriaLabelledby,
+    };
+  }, [ariaDescribedby, ariaLabel, ariaLabelledby, descriptionId, titleId]);
+};

src/components/ChannelListItem/ChannelListItemActionButtons.tsx

@@ -2,7 +2,7 @@ import React, { type ComponentProps, type ComponentType, type ReactNode } from '
 
 import clsx from 'clsx';
 import { ContextMenu, useDialogIsOpen, useDialogOnNearestManager } from '../Dialog';
-import { useComponentContext } from '../../context';
+import { useComponentContext, useTranslationContext } from '../../context';
 import {
   defaultChannelActionSet,
   useBaseChannelActionSetFilter,
@@ -20,6 +20,7 @@ interface ChannelListItemActionButtonsInterface {
 
 export const ChannelListItemActionButtons: ChannelListItemActionButtonsInterface = () => {
   const { ContextMenu: ContextMenuComponent = ContextMenu } = useComponentContext();
+  const { t } = useTranslationContext();
   const { channel } = useChannelListItemContext();
   const [referenceElement, setReferenceElement] =
     React.useState<HTMLButtonElement | null>(null);
@@ -52,6 +53,7 @@ export const ChannelListItemActionButtons: ChannelListItemActionButtonsInterface
         <Component key={type} />
       ))}
       <ContextMenuComponent
+        aria-label={t('aria/Channel Actions')}
         className='str-chat__channel-list-item__action-buttons-context-menu'
         dialogManagerId={dialogManager?.id}
         id={dialog.id}

src/components/ChannelListItem/__tests__/ChannelListItemActionButtons.defaults.test.tsx

@@ -127,6 +127,8 @@ describe('ChannelListItemActionButtons defaults', () => {
     });
 
     const menu = document.querySelector('.str-chat__context-menu') as HTMLElement;
+    expect(menu).toHaveAttribute('aria-label');
+    expect(menu.getAttribute('aria-label')).toBeTruthy();
     act(() => {
       fireEvent.click(within(menu).getByRole('menuitem', { name: 'Block User' }));
     });

src/components/Dialog/components/Alert.tsx

@@ -1,7 +1,7 @@
 import React, { type ComponentProps, type ComponentType, forwardRef } from 'react';
 import clsx from 'clsx';
 import { useModalContext } from '../../../context';
-import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
+import { useAriaIdentifiers } from '../../../a11y/hooks/useAriaIdentifiers';
 
 export const Root = forwardRef<HTMLDivElement, ComponentProps<'div'>>(function AlertRoot(
   { children, className, ...props }: ComponentProps<'div'>,

src/components/Dialog/components/Prompt.tsx

@@ -3,7 +3,7 @@ import clsx from 'clsx';
 import { Button, type ButtonProps } from '../../Button';
 import { IconXmark } from '../../Icons';
 import { useModalContext, useTranslationContext } from '../../../context';
-import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
+import { useAriaIdentifiers } from '../../../a11y/hooks/useAriaIdentifiers';
 
 const PromptRoot = ({ children, className, ...props }: ComponentProps<'div'>) => (
   <div {...props} className={clsx('str-chat__prompt', className)}>
@@ -50,6 +50,9 @@ const PromptHeader = ({
       {close && (
         <Button
           appearance='ghost'
+          aria-describedby={
+            description != null && description !== '' ? resolvedDescriptionId : undefined
+          }
           aria-label={t('Close prompt: {{ title }}', { title })}
           circular
           className='str-chat__prompt__header__close-button'

src/components/Dialog/components/Viewer.tsx

@@ -3,7 +3,7 @@ import clsx from 'clsx';
 import { Button, type ButtonProps } from '../../Button';
 import { IconArrowLeft, IconXmark } from '../../Icons';
 import { useModalContext, useTranslationContext } from '../../../context';
-import { useAriaIdentifiers } from '../../../hooks/useAriaIdentifiers';
+import { useAriaIdentifiers } from '../../../a11y/hooks/useAriaIdentifiers';
 
 const ViewerRoot = ({ children, className, ...props }: ComponentProps<'div'>) => (
   <div {...props} className={clsx('str-chat__viewer', className)}>
@@ -42,6 +42,9 @@ const ViewerHeader = ({
       {goBack && (
         <Button
           appearance='ghost'
+          aria-describedby={
+            description != null && description !== '' ? resolvedDescriptionId : undefined
+          }
           aria-label={t('Back')}
           circular
           className='str-chat__viewer__header__go-back-button'
@@ -65,7 +68,10 @@ const ViewerHeader = ({
       {close && (
         <Button
           appearance='ghost'
-          aria-label={t('Close')}
+          aria-describedby={
+            description != null && description !== '' ? resolvedDescriptionId : undefined
+          }
+          aria-label={t('Close dialog')}
           circular
           className='str-chat__viewer__header__close-button'
           onClick={close}

src/components/Dialog/styling/Prompt.scss

@@ -20,6 +20,7 @@
     }
 
     .str-chat__prompt__header__title {
+      margin: 0;
       font: var(--str-chat__font-heading-sm);
       color: var(--text-primary);
     }
@@ -30,8 +31,10 @@
     }
 
     .str-chat__prompt__header__close-button {
+      align-self: flex-start;
       flex-shrink: 0;
       color: var(--text-primary);
+
       .str-chat__icon {
         width: var(--icon-size-md);
         height: var(--icon-size-md);

src/components/Dialog/styling/Viewer.scss

@@ -25,6 +25,7 @@
     }
 
     .str-chat__viewer__header__title {
+      margin: 0;
       font: var(--str-chat__font-heading-sm);
       color: var(--text-primary);
     }
@@ -43,6 +44,7 @@
     }
 
     .str-chat__viewer__header__close-button {
+      align-self: flex-start;
       flex-shrink: 0;
       color: var(--text-primary);
     }

src/components/Form/NumericInput.tsx

@@ -132,13 +132,17 @@ export const NumericInput = forwardRef<HTMLInputElement, NumericInputProps>(
             <IconMinus className='str-chat__form-numeric-input__stepper-icon' />
           </Button>
           <input
+            aria-valuemax={Number.isFinite(maxDef) ? maxDef : undefined}
+            aria-valuemin={Number.isFinite(minDef) ? minDef : undefined}
+            aria-valuenow={num ?? undefined}
             className='str-chat__form-numeric-input__input'
             disabled={disabled}
             id={id}
             inputMode='numeric'
             onChange={handleInputChange}
             onKeyDown={handleKeyDown}
             ref={ref}
+            role='spinbutton'
             type='text'
             value={value}
             {...inputProps}