fix: give every dialog an accessible name and description

src/plugins/frontmatter/FrontmatterEditor.tsx

@@ -74,6 +74,9 @@ export const FrontmatterEditor = ({ yaml, onChange }: FrontmatterEditorProps) =>
           <Dialog.Overlay className={styles.dialogOverlay} />
           <Dialog.Content className={styles.largeDialogContent} data-editor-type="frontmatter">
             <Dialog.Title className={styles.dialogTitle}>{t('frontmatterEditor.title', 'Edit document frontmatter')}</Dialog.Title>
+            <Dialog.Description className={styles.visuallyHidden}>
+              {t('frontmatterEditor.dialogDescription', 'Add, edit, or remove the key-value entries of the document frontmatter.')}
+            </Dialog.Description>
             <form
               onSubmit={(e) => {
                 void handleSubmit(onSubmit)(e)

src/plugins/image/ImageDialog.tsx

@@ -66,6 +66,9 @@ export const ImageDialog: React.FC = () => {
           }}
         >
           <Dialog.Title>{t('uploadImage.dialogTitle', 'Upload an image')}</Dialog.Title>
+          <Dialog.Description className={styles.visuallyHidden}>
+            {t('uploadImage.dialogDescription', 'Insert an image from a URL or upload one from your device.')}
+          </Dialog.Description>
           <form
             onSubmit={async (e) => {
               e.preventDefault()

src/plugins/toolbar/primitives/DialogButton.tsx

@@ -70,6 +70,8 @@ export const DialogButton = React.forwardRef<
       <Dialog.Portal container={editorRootElementRef?.current}>
         <Dialog.Overlay className={styles.dialogOverlay} />
         <Dialog.Content className={styles.dialogContent}>
+          <Dialog.Title className={styles.visuallyHidden}>{tooltipTitle}</Dialog.Title>
+          <Dialog.Description className={styles.visuallyHidden}>{dialogInputPlaceholder}</Dialog.Description>
           <DialogForm
             submitButtonTitle={submitButtonTitle}
             autocompleteSuggestions={autocompleteSuggestions}

src/styles/ui.module.css

@@ -627,6 +627,20 @@
   padding-left: var(--spacing-2);
 }
 
+/* Keeps text available to assistive technology without rendering it on screen. */
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border-width: 0;
+}
+
 .dialogCloseButton {
   @mixin clear-form-element;
   position: absolute;

src/test/dialog-a11y.test.tsx

@@ -0,0 +1,86 @@
+import { useRealm } from '@mdxeditor/gurx'
+import { fireEvent, render, screen } from '@testing-library/react'
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+import { MDXEditor, frontmatterPlugin, imagePlugin, insertFrontmatter$, toolbarPlugin } from '../'
+import { InsertImage } from '../plugins/toolbar/components/InsertImage'
+import { DialogButton } from '../plugins/toolbar/primitives/DialogButton'
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+const FrontmatterTrigger = () => {
+  const realm = useRealm()
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        realm.pub(insertFrontmatter$)
+      }}
+    >
+      Edit frontmatter
+    </button>
+  )
+}
+
+/**
+ * Asserts that the open dialog with the given accessible name wires an
+ * `aria-describedby` to an element carrying the expected description text.
+ * Radix warns (and screen readers get no context) when this wiring is missing.
+ */
+function expectDialogDescription(name: string, description: string) {
+  const dialog = screen.getByRole('dialog', { name })
+  const describedById = dialog.getAttribute('aria-describedby')
+  expect(describedById).toBeTruthy()
+  const descriptionElement = document.getElementById(describedById!)
+  expect(descriptionElement).toHaveTextContent(description)
+}
+
+describe('editor dialog accessibility', () => {
+  it('describes the image dialog', () => {
+    render(<MDXEditor markdown="" plugins={[imagePlugin(), toolbarPlugin({ toolbarContents: () => <InsertImage /> })]} />)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Insert image' }))
+
+    expectDialogDescription('Upload an image', 'Insert an image from a URL or upload one from your device.')
+  })
+
+  it('names and describes the shared toolbar dialog', () => {
+    render(
+      <MDXEditor
+        markdown=""
+        plugins={[
+          toolbarPlugin({
+            toolbarContents: () => (
+              <DialogButton
+                tooltipTitle="Insert YouTube video"
+                dialogInputPlaceholder="Paste URL"
+                submitButtonTitle="Insert video"
+                onSubmit={() => undefined}
+                buttonContent="video"
+              />
+            )
+          })
+        ]}
+      />
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Insert YouTube video' }))
+
+    expectDialogDescription('Insert YouTube video', 'Paste URL')
+  })
+
+  it('describes the frontmatter dialog', async () => {
+    render(
+      <MDXEditor
+        markdown={'---\ntitle: hello\n---\n\n# body'}
+        plugins={[frontmatterPlugin(), toolbarPlugin({ toolbarContents: () => <FrontmatterTrigger /> })]}
+      />
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Edit frontmatter' }))
+
+    await screen.findByRole('dialog', { name: 'Edit document frontmatter' })
+    expectDialogDescription('Edit document frontmatter', 'Add, edit, or remove the key-value entries of the document frontmatter.')
+  })
+})