Skip to content

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.md
new file mode 100644
index 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.tsx
new file mode 100644
index 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`](u)', ['a b c']],
+ ['a link', '![a [b](u) c](v)', ['a b c']],
+ ['an image', '![a ![b](u) c](v)', ['a b c']],
+ ['escapes and character references', '![&amp; \\* x](u)', ['& * x']],
+ ['plain text, unchanged', '![a photo](u)', ['a photo']],
+ [
+ 'a hard break as a line ending',
+ '![first \nsecond](u)',
+ ['first\nsecond'],
+ ],
+ [
+ 'a backslash hard break as a line ending',
+ '![first\\\nsecond](u)',
+ ['first\nsecond'],
+ ],
+ ['a soft break as a line ending', '![first\nsecond](u)', ['first\nsecond']],
+ [
+ 'a hard break inside emphasis',
+ '![*first \nsecond*](u)',
+ ['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('![*a* `b`](/i.png)')).toEqual(['a b']);
+ });
+
+ it('reads a description ten images deep, and keeps the source deeper', () => {
+ const nested = (levels: number) =>
+ `${'!['.repeat(levels)}*a*${'](u)'.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)}a${'](u)'.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.ts
index 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++;