An open source design system that's fully customizable and agent ready
TypeScript
fix(Markdown): decode character references and escapes in image alt text (#6993)
Cindy Zhangc8d8a1d26147
diff --git a/.changeset/markdown-image-alt-references.md b/.changeset/markdown-image-alt-references.mdnew file mode 100644index 0000000000..a960bd1159--- /dev/null+++ b/.changeset/markdown-image-alt-references.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': patch+---++[fix] Markdown image alt text shows character references and escapes as the characters they name++`` gave the image the alt text `Fish & chips`, so a screen reader announced "amp". Alt text now resolves character references and backslash escapes the same way body text does, for inline, standalone, and reference-style images; an escaped `&` and unknown names stay literal.++@cixzhangdiff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsxindex f2a61391da..d6705df48b 100644--- a/packages/core/src/Markdown/Markdown.test.tsx+++ b/packages/core/src/Markdown/Markdown.test.tsx@@ -348,6 +348,17 @@ describe('Markdown', () => {expect(container.querySelector('code')?.textContent).toBe('&');});+ it('names an image with decoded alt text', () => {+ render(+ <Markdown>+ {''}+ </Markdown>,+ );+ expect(+ screen.getByRole('img', {name: 'Fish & chips *fresh*'}),+ ).toBeInTheDocument();+ });+it('adds target="_blank" to external links', () => {render(<Markdown>{'[ext](https://example.com)'}</Markdown>);const link = screen.getByText('ext');diff --git a/packages/core/src/Markdown/characterReferences.ts b/packages/core/src/Markdown/characterReferences.tsindex 2e486c1d8a..030e27659b 100644--- a/packages/core/src/Markdown/characterReferences.ts+++ b/packages/core/src/Markdown/characterReferences.ts@@ -4,7 +4,9 @@* @file characterReferences.ts* @input The HTML named character references, inlined below.* @output matchCharacterReference: the character a `&name;`, `&#N;`, or- * `&#xH;` reference names, and where the reference ends.+ * `&#xH;` reference names, and where the reference ends. decodeLiteralText:+ * text with backslash escapes and character references resolved, for text+ * that is not parsed as Markdown, such as an image's alt text.* @position Used by parser.ts while it parses inline text, so references* render as the characters they name (spec:AST-061 FR7, DEC-3). Code spans* and code blocks never reach it and keep references literal.@@ -73,3 +75,35 @@ export function matchCharacterReference((codePoint < 0xd800 || codePoint > 0xdfff);return {value: isValid ? String.fromCodePoint(codePoint) : '\uFFFD', end};}++/**+ * Resolves backslash escapes and character references the way inline parsing+ * does, for text that is shown as written rather than parsed as Markdown, such+ * as an image's alt text. An escaped `&` stays literal.+ */+export function decodeLiteralText(text: string): string {+ if (!text.includes('\\') && !text.includes('&')) {+ return text;+ }+ let output = '';+ let index = 0;+ while (index < text.length) {+ const character = text[index];+ if (character === '\\' && index + 1 < text.length) {+ output += text[index + 1];+ index += 2;+ continue;+ }+ if (character === '&') {+ const reference = matchCharacterReference(text, index);+ if (reference != null) {+ output += reference.value;+ index = reference.end;+ continue;+ }+ }+ output += character;+ index++;+ }+ return output;+}diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.tsindex edf95eac19..74caf33297 100644--- a/packages/core/src/Markdown/parser.test.ts+++ b/packages/core/src/Markdown/parser.test.ts@@ -358,6 +358,28 @@ describe('parseInline', () => {});});+ it('decodes character references and escapes in image alt text', () => {+ expect(parseInline('')).toEqual([+ {type: 'image', src: 'fish.png', alt: 'Fish & chips *fresh*'},+ ]);+ expect(parseMarkdown('')[0]).toMatchObject({+ type: 'image',+ alt: '\u00a9 2026 \u00a9',+ });+ expect(+ parseMarkdown('![Q&A][logo]\n\n[logo]: /logo.png')[0],+ ).toMatchObject({+ type: 'paragraph',+ children: [{type: 'image', src: '/logo.png', alt: 'Q&A'}],+ });+ });++ it('keeps an escaped ampersand and unknown names literal in alt text', () => {+ expect(parseInline('')).toEqual([+ {type: 'image', src: 'x.png', alt: '& &nope;'},+ ]);+ });+it('handles parentheses in image URLs', () => {const result = parseInline('.png)');expect(result[0].type).toBe('image');diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.tsindex da3a93d810..dca8858653 100644--- a/packages/core/src/Markdown/parser.ts+++ b/packages/core/src/Markdown/parser.ts@@ -38,7 +38,10 @@ import type {PreparedMarkdownPlugins,PreparedSyntaxContribution,} from './plugins/protocol';-import {matchCharacterReference} from './characterReferences';+import {+ decodeLiteralText,+ matchCharacterReference,+} from './characterReferences';import {isSafeMarkdownParserUrl} from './url';// ---------------------------------------------------------------------------@@ -1027,7 +1030,10 @@ function matchReferenceImage(const label = rawLabel === '' ? alt : rawLabel;const src = linkDefs.get(normalizeLinkLabel(label));if (src != null && isSafeMarkdownParserUrl(src)) {- return {node: {type: 'image', url: src, alt}, end: labelClose + 1};+ return {+ node: {type: 'image', url: src, alt: decodeLiteralText(alt)},+ end: labelClose + 1,+ };}// No match — fall back to a shortcut `![alt]`.}@@ -1039,7 +1045,10 @@ function matchReferenceImage(if (src == null || !isSafeMarkdownParserUrl(src)) {return null;}- return {node: {type: 'image', url: src, alt}, end: altClose + 1};+ return {+ node: {type: 'image', url: src, alt: decodeLiteralText(alt)},+ end: altClose + 1,+ };}// ---------------------------------------------------------------------------@@ -1535,7 +1544,7 @@ function parseInlineImpl(nodes.push({type: 'image',url: src,- alt: text.slice(i + 2, altClose),+ alt: decodeLiteralText(text.slice(i + 2, altClose)),});}i = srcClose + 1;@@ -2753,7 +2762,11 @@ function parseMarkdownImpl(line.trim() === imageMatch[0] &&isSafeMarkdownParserUrl(imageSrc)) {- pushBlock({type: 'image', alt: imageMatch[1], url: imageSrc});+ pushBlock({+ type: 'image',+ alt: decodeLiteralText(imageMatch[1]),+ url: imageSrc,+ });index++;continue;}