An open source design system that's fully customizable and agent ready
TypeScript
fix(Markdown): give an image the plain text of its description as alt text (#7091)
Cindy Zhang12bd580b47d0
diff --git a/.changeset/markdown-image-alt-plain-text.md b/.changeset/markdown-image-alt-plain-text.mdnew file mode 100644index 0000000000..97bf7208f4--- /dev/null+++ b/.changeset/markdown-image-alt-plain-text.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+---++[fix] Markdown: give an image the plain text of its description as alt text+@cixzhang++`Markdown` now reads an image's description as inline content and uses its plain text as the alt text, as CommonMark specifies, so ``![`a]b` *c*](u)`` has the alt `a]b c` rather than the raw source with its backticks and asterisks.diff --git a/packages/core/src/Markdown/imageAlt.test.tsx b/packages/core/src/Markdown/imageAlt.test.tsxnew file mode 100644index 0000000000..abc4119445--- /dev/null+++ b/packages/core/src/Markdown/imageAlt.test.tsx@@ -0,0 +1,84 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {parseInlineAst, parseMarkdownAst} from './parser';++type Json = {type: string; alt?: string; children?: Json[]};++/** Every image's alt text, in order, searched iteratively. */+function alts(nodes: ReadonlyArray<Json>): string[] {+ const found: string[] = [];+ const stack = [...nodes].reverse();+ while (stack.length > 0) {+ const node = stack.pop() as Json;+ if (node.type === 'image') {+ found.push(node.alt ?? '');+ }+ stack.push(...[...(node.children ?? [])].reverse());+ }+ return found;+}++const inlineAlts = (markdown: string): string[] =>+ alts(parseInlineAst(markdown) as unknown as Json[]);++const documentAlts = (markdown: string): string[] =>+ alts(parseMarkdownAst(markdown).children as unknown as Json[]);++describe("an image's alt text is its description as plain text (CommonMark 0.31 §6.4)", () => {+ it.each([+ ['code', '![`a]b`](u)', ['a]b']],+ ['emphasis, strong, and code', '', ['a b c']],+ ['a link', ' c](v)', ['a b c']],+ ['an image', ' c](v)', ['a b c']],+ ['escapes and character references', '', ['& * x']],+ ['plain text, unchanged', '', ['a photo']],+ [+ 'a hard break as a line ending',+ '',+ ['first\nsecond'],+ ],+ [+ 'a backslash hard break as a line ending',+ '',+ ['first\nsecond'],+ ],+ ['a soft break as a line ending', '', ['first\nsecond']],+ [+ 'a hard break inside emphasis',+ '',+ ['first\nsecond'],+ ],+ ])('reads %s: %j', (_, markdown, expected) => {+ expect(inlineAlts(markdown)).toEqual(expected);+ });++ it('reads a reference image the same way', () => {+ expect(documentAlts('![*a*][r]\n\n[r]: /i.png')).toEqual(['a']);+ });++ it('reads an image on its own line the same way', () => {+ expect(documentAlts('')).toEqual(['a b']);+ });++ it('reads a description ten images deep, and keeps the source deeper', () => {+ const nested = (levels: number) =>+ `${''.repeat(levels)}`;+ expect(inlineAlts(nested(10))[0]).toBe('a');+ expect(inlineAlts(nested(12))[0]).toContain('*a*');+ });++ it('reads images nested 20,000 deep without exhausting the stack, in time', () => {+ const markdown = `${''.repeat(20_000)}`;+ expect(() => parseInlineAst(markdown)).not.toThrow();+ let fastest = Number.POSITIVE_INFINITY;+ for (let round = 0; round < 3; round++) {+ const started = performance.now();+ parseInlineAst(markdown);+ fastest = Math.min(fastest, performance.now() - started);+ }+ // Alone it takes about 40 ms; the budget leaves room for a loaded test+ // machine.+ expect(fastest).toBeLessThan(1000);+ });+});diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.tsindex 0fc135c9d7..cbdedfe74f 100644--- a/packages/core/src/Markdown/parser.ts+++ b/packages/core/src/Markdown/parser.ts@@ -11,6 +11,7 @@import {getMarkdownAstLegacyCodeLanguage,+ markdownAstText,markMarkdownAstLegacyCodeLanguage,} from './ast';import type {@@ -1055,11 +1056,77 @@ function matchReferenceLink(}/** Reference-image equivalent of {@link matchReferenceLink} (`![alt][label]`). */+/** How many image descriptions enclose the one being read. */+let imageAltDepth = 0;++/**+ * The deepest image descriptions are read as inline content. Reading one+ * reads every image nested in it again, so the cost grows with the depth+ * times the text; ten levels keep any input fast, and no real image nests+ * that deep.+ */+const MAX_IMAGE_ALT_DEPTH = 10;++/**+ * An image's alt text: its description read as inline content and taken as+ * plain text (CommonMark 0.31 §6.4), so `` ![`a]b` *c*](u) `` has the alt+ * `a]b c`. Descriptions nested deeper than MAX_IMAGE_ALT_DEPTH keep their+ * decoded source.+ */+function imageAlt(+ description: string,+ opts: ResolvedOptions,+ context: 'default' | 'tableCell',+): string {+ if (imageAltDepth >= MAX_IMAGE_ALT_DEPTH) {+ return decodeLiteralText(description);+ }+ imageAltDepth++;+ try {+ return markdownAstText(+ breaksAsLineEndings(+ parseInlineImpl(description, protectedInlineOptions(opts), context),+ ),+ );+ } finally {+ imageAltDepth--;+ }+}++/**+ * `nodes` with each hard line break as the line ending it stands for, so an+ * alt text keeps the words on either side apart, as commonmark.js writes it.+ */+function breaksAsLineEndings(+ nodes: ReadonlyArray<MarkdownAstPhrasingContent<RuntimeExtensionNode>>,+): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {+ return nodes.map(node => {+ switch (node.type) {+ case 'break':+ return {type: 'text', value: '\n'};+ case 'strong':+ case 'emphasis':+ case 'delete':+ case 'link':+ return {...node, children: breaksAsLineEndings(node.children)};+ case 'text':+ case 'inlineCode':+ case 'inlineMath':+ case 'image':+ case 'citation':+ case 'extension':+ return node;+ }+ });+}+function matchReferenceImage(text: string,start: number,linkDefs: ReadonlyMap<string, string>,inlineIndex: InlineIndex,+ opts: ResolvedOptions,+ context: 'default' | 'tableCell',): {node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;end: number;@@ -1077,7 +1144,7 @@ function matchReferenceImage(const src = linkDefs.get(normalizeLinkLabel(label));if (src != null && isSafeMarkdownParserUrl(src)) {return {- node: {type: 'image', url: src, alt: decodeLiteralText(alt)},+ node: {type: 'image', url: src, alt: imageAlt(alt, opts, context)},end: labelClose + 1,};}@@ -1092,7 +1159,7 @@ function matchReferenceImage(return null;}return {- node: {type: 'image', url: src, alt: decodeLiteralText(alt)},+ node: {type: 'image', url: src, alt: imageAlt(alt, opts, context)},end: altClose + 1,};}@@ -2276,7 +2343,7 @@ function parseInlineImpl(nodes.push({type: 'image',url: src,- alt: decodeLiteralText(text.slice(i + 2, altClose)),+ alt: imageAlt(text.slice(i + 2, altClose), opts, context),});}i = srcClose + 1;@@ -2287,7 +2354,14 @@ function parseInlineImpl(// --- Reference image ![alt][label] / ![alt][] / ![alt] ---if (opts.linkDefs != null && text[i] === '!' && text[i + 1] === '[') {- const ref = matchReferenceImage(text, i, opts.linkDefs, inlineIndex);+ const ref = matchReferenceImage(+ text,+ i,+ opts.linkDefs,+ inlineIndex,+ opts,+ context,+ );if (ref) {nodes.push(ref.node);i = ref.end;@@ -3511,7 +3585,7 @@ function parseMarkdownImpl() {pushBlock({type: 'image',- alt: decodeLiteralText(imageMatch[1]),+ alt: imageAlt(imageMatch[1], opts, 'default'),url: imageSrc,});index++;