From 309dde5423d6198e0f58ff003799233e425abb42 Mon Sep 17 00:00:00 2001
From: AK <144495202+AKnassa@users.noreply.github.com>
Date: Mon, 3 Aug 2026 13:55:56 -0400
Subject: [PATCH] fix(a11y): name RichTextEditor editable surfaces

axe flagged every RichTextEditor story (aria-input-field-name,
12 serious + 1 critical label): the editor pointed aria-labelledby
at an id no element carried, RichTextView's read-only textbox had
no name at all, and one story shipped a bare textarea.

- point aria-labelledby at the label element via Field's labelID,
  and give the contenteditable the control id htmlFor expects
- add a label prop to RichTextView (default 'Rich text content'),
  mirroring RichTextEditorToolbar's label default
- label the Markdown Serializers story textarea
- burn 13 fixed entries out of .github/a11y-baseline.json (226->213)

Verified: 53/53 lab tests, lab typecheck:docs, storybook typecheck,
and the full axe audit on all 12 stories - 0 violations, gate green.

Part of #4681.
---
 .github/a11y-baseline.json                    | 65 -------------------
 .../stories/RichTextEditor.stories.tsx        | 20 ++++--
 .../RichTextEditor/RichTextEditor.test.tsx    | 25 +++++++
 .../lab/src/RichTextEditor/RichTextEditor.tsx | 14 +++-
 .../lab/src/RichTextEditor/RichTextView.tsx   | 13 +++-
 5 files changed, 60 insertions(+), 77 deletions(-)

diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index 84e9c710ad67..3f3bfdeabeed 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -803,71 +803,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "RichTextEditor::Controlled Persistence::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Custom Transformers::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Default::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Error Status::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Imperative Ref::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Markdown Serializers::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Markdown Serializers::label",
-      "impact": "critical",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/label?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Read Only::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::Required::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::With Character Limit::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::With Description::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::With Initial Value::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
-    {
-      "key": "RichTextEditor::With Toolbar::aria-input-field-name",
-      "impact": "serious",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/aria-input-field-name?application=playwright"
-    },
     {
       "key": "Schedule::Async Loader::color-contrast",
       "impact": "serious",
diff --git a/apps/storybook/stories/RichTextEditor.stories.tsx b/apps/storybook/stories/RichTextEditor.stories.tsx
index 9d65dca39b35..8948324fb4d0 100644
--- a/apps/storybook/stories/RichTextEditor.stories.tsx
+++ b/apps/storybook/stories/RichTextEditor.stories.tsx
@@ -72,7 +72,8 @@ export const WithCharacterLimit: Story = {
   args: {
     label: 'Bio',
     maxLength: 80,
-    description: 'A character counter appears below the editor when maxLength is set.',
+    description:
+      'A character counter appears below the editor when maxLength is set.',
     placeholder: 'Type past 80 characters to see the counter turn red…',
   },
 };
@@ -159,7 +160,7 @@ export const ControlledPersistence = {
           <div style={{fontWeight: 600, marginBottom: 8}}>
             RichTextView (read-only render of the same content)
           </div>
-          <RichTextView value={json} />
+          <RichTextView value={json} label="Saved content preview" />
         </div>
       </div>
     );
@@ -190,7 +191,9 @@ export const ImperativeRef = {
             onClick={() => {
               const state = ref.current?.getEditorState();
               const text = state?.read(() => $getRoot().getTextContent());
-              setReadout(`getEditorState() text content: ${JSON.stringify(text)}`);
+              setReadout(
+                `getEditorState() text content: ${JSON.stringify(text)}`,
+              );
             }}>
             getEditorState()
           </button>
@@ -277,12 +280,15 @@ export const MarkdownSerializers = {
     return (
       <div style={{display: 'grid', gap: 24, maxWidth: 720}}>
         <div>
-          <div style={{fontWeight: 600, marginBottom: 8}}>
+          <label
+            htmlFor="rte-markdown-input"
+            style={{display: 'block', fontWeight: 600, marginBottom: 8}}>
             1. Input Markdown (edit me)
-          </div>
+          </label>
           <textarea
+            id="rte-markdown-input"
             value={markdown}
-            onChange={(e) => setMarkdown(e.target.value)}
+            onChange={e => setMarkdown(e.target.value)}
             rows={10}
             style={{
               width: '100%',
@@ -314,7 +320,7 @@ export const MarkdownSerializers = {
           <div style={{fontWeight: 600, marginBottom: 8}}>
             3. Same JSON rendered read-only via RichTextView
           </div>
-          <RichTextView value={json} />
+          <RichTextView value={json} label="Serialized content preview" />
         </div>
 
         <div>
diff --git a/packages/lab/src/RichTextEditor/RichTextEditor.test.tsx b/packages/lab/src/RichTextEditor/RichTextEditor.test.tsx
index def7235ed806..f7611aea82f5 100644
--- a/packages/lab/src/RichTextEditor/RichTextEditor.test.tsx
+++ b/packages/lab/src/RichTextEditor/RichTextEditor.test.tsx
@@ -180,6 +180,14 @@ describe('RichTextEditor', () => {
     expect(screen.getByText('Notes')).toBeInTheDocument();
   });
 
+  it('names the textbox from the visible label', () => {
+    // The contenteditable surface is a <div>, so a <label htmlFor> association
+    // does not apply — the accessible name must come from aria-labelledby
+    // pointing at the label element's id (axe: aria-input-field-name).
+    render(<RichTextEditor label="Notes" />);
+    expect(screen.getByRole('textbox', {name: 'Notes'})).toBeInTheDocument();
+  });
+
   it('shows the placeholder when empty', () => {
     render(<RichTextEditor label="Notes" placeholder="Write something…" />);
     expect(screen.getByText('Write something…')).toBeInTheDocument();
@@ -573,6 +581,23 @@ describe('RichTextView', () => {
     );
   });
 
+  it('names the read-only textbox with a default accessible name', () => {
+    // Lexical's ContentEditable keeps role="textbox" (with aria-readonly) even
+    // when non-editable, so the region must carry an accessible name
+    // (axe: aria-input-field-name).
+    render(<RichTextView value={HELLO_STATE} />);
+    expect(
+      screen.getByRole('textbox', {name: 'Rich text content'}),
+    ).toBeInTheDocument();
+  });
+
+  it('names the read-only textbox from the label prop', () => {
+    render(<RichTextView value={HELLO_STATE} label="Meeting notes" />);
+    expect(
+      screen.getByRole('textbox', {name: 'Meeting notes'}),
+    ).toBeInTheDocument();
+  });
+
   it('renders custom read-only plugins passed via the plugins prop', () => {
     render(
       <RichTextView
diff --git a/packages/lab/src/RichTextEditor/RichTextEditor.tsx b/packages/lab/src/RichTextEditor/RichTextEditor.tsx
index e3c97dbb6cab..fc38a583f5fa 100644
--- a/packages/lab/src/RichTextEditor/RichTextEditor.tsx
+++ b/packages/lab/src/RichTextEditor/RichTextEditor.tsx
@@ -414,6 +414,7 @@ export const RichTextEditor = forwardRef<
 ) {
   const size = useSize(sizeProp, 'md');
   const id = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const placeholderID = useId();
@@ -465,6 +466,7 @@ export const RichTextEditor = forwardRef<
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={labelID}
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}
@@ -503,8 +505,9 @@ export const RichTextEditor = forwardRef<
             <RichTextPlugin
               contentEditable={
                 <EditorContentEditable
+                  id={id}
                   ariaLabel={isLabelHidden ? label : undefined}
-                  ariaLabelledBy={isLabelHidden ? undefined : id}
+                  ariaLabelledBy={isLabelHidden ? undefined : labelID}
                   ariaDescribedBy={ariaDescribedBy}
                   ariaRequired={isRequired && !isOptional}
                   ariaInvalid={status?.type === 'error'}
@@ -629,7 +632,9 @@ function EditorRefBridge({
         // $generateHtmlFromNodes serializes the whole document (null selection)
         // to HTML; must run in a read context and requires a DOM.
         // `@lexical/html` is a subpackage (built dist) — safe.
-        editor.getEditorState().read(() => $generateHtmlFromNodes(editor, null)),
+        editor
+          .getEditorState()
+          .read(() => $generateHtmlFromNodes(editor, null)),
       getEditor: () => editor,
     }),
     [editor, editable, transformers],
@@ -659,7 +664,7 @@ function CharCountPlugin({
     // `declare` class fields) and fails. Both APIs used here are methods on the
     // editor instance, so no top-level `lexical` value import is needed.
     onCountChange(editor.getRootElement()?.textContent?.length ?? 0);
-    return editor.registerTextContentListener((textContent) => {
+    return editor.registerTextContentListener(textContent => {
       onCountChange(textContent.length);
     });
   }, [editor, onCountChange]);
@@ -672,6 +677,7 @@ function CharCountPlugin({
  * neither) is satisfied by two concrete branches rather than a spread.
  */
 function EditorContentEditable({
+  id,
   ariaLabel,
   ariaLabelledBy,
   ariaDescribedBy,
@@ -681,6 +687,7 @@ function EditorContentEditable({
   placeholderID,
   rest,
 }: {
+  id: string;
   ariaLabel?: string;
   ariaLabelledBy?: string;
   ariaDescribedBy?: string;
@@ -691,6 +698,7 @@ function EditorContentEditable({
   rest: Record<string, unknown>;
 }) {
   const shared = {
+    id,
     role: 'textbox' as const,
     'aria-multiline': 'true' as const,
     'aria-label': ariaLabel,
diff --git a/packages/lab/src/RichTextEditor/RichTextView.tsx b/packages/lab/src/RichTextEditor/RichTextView.tsx
index 8444f2b6565f..3ae4fc7a7172 100644
--- a/packages/lab/src/RichTextEditor/RichTextView.tsx
+++ b/packages/lab/src/RichTextEditor/RichTextView.tsx
@@ -10,7 +10,7 @@
  *   (lab), re-exported from @astryxdesign/lab
  *
  * SYNC: When modified, update these files to stay in sync:
- * - /packages/lab/src/RichTextEditor/RichTextView.test.tsx
+ * - /packages/lab/src/RichTextEditor/RichTextEditor.test.tsx (RichTextView describe block)
  * - /packages/lab/src/RichTextEditor/index.ts
  * - /packages/lab/src/index.ts (barrel re-export)
  * - /apps/storybook/stories/RichTextEditor.stories.tsx
@@ -57,6 +57,14 @@ export interface RichTextViewProps extends BaseProps {
    * `JSON.stringify(editorState.toJSON())`).
    */
   value: string;
+  /**
+   * Accessible name for the read-only text region. Lexical renders the region
+   * with `role="textbox"` (plus `aria-readonly`) even when non-editable, so it
+   * must carry a name for screen readers. Override with something contextual
+   * (e.g. `'Meeting notes'`).
+   * @default 'Rich text content'
+   */
+  label?: string;
   /**
    * Additional Lexical nodes to register beyond the default OSS set. Must match
    * the nodes used to author `value` so custom node types deserialize.
@@ -98,6 +106,7 @@ export interface RichTextViewProps extends BaseProps {
  */
 export function RichTextView({
   value,
+  label = 'Rich text content',
   nodes,
   plugins,
   namespace = 'astryx-view',
@@ -171,7 +180,7 @@ export function RichTextView({
       {...rest}>
       <LexicalComposer initialConfig={initialConfig}>
         <RichTextPlugin
-          contentEditable={<ContentEditable />}
+          contentEditable={<ContentEditable aria-label={label} />}
           placeholder={null}
           ErrorBoundary={LexicalErrorBoundary}
         />