Merge branch 'fix/source-srcset' into dev

Gerrit0 · Gerrit0 · commit 07d831525d18 · 2025-07-27T13:05:22.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,9 +10,15 @@ title: Changelog
 - Permit `-` within tag names to support `typescript-json-schema`'s `@TJS-type` tag, #2972.
 - Exposed `Context.createSymbolId` for use by plugins.
 
+### Bug Fixes
+
+- Relative links in `<img srcset>` will now be discovered by TypeDoc, #2975.
+- Relative links in `<source src>` and `<source srcset>` elements will now be discovered by TypeDoc, #2975.
+
 ### Thanks!
 
 - @jonathanhefner
+- @laymonage
 
 ## v0.28.7 (2025-06-30)
 
diff --git a/index.html b/index.html
@@ -0,0 +1,6 @@
+<!doctype html>
+<body>
+    <picture>
+        <img width="343" src="   .github/wagtailb.svg   " alt="Wagtail">
+    </picture>
+</body>
diff --git a/src/lib/converter/comments/textParser.ts b/src/lib/converter/comments/textParser.ts
@@ -136,9 +136,11 @@ export function textContent(
             continue;
         }
 
-        const tagLink = checkTagLink(data);
-        if (tagLink) {
-            addRef(tagLink);
+        const tagLinks = checkTagLink(data);
+        if (tagLinks.length) {
+            for (const tagLink of tagLinks) {
+                addRef(tagLink);
+            }
             continue;
         }
 
@@ -297,52 +299,152 @@ function checkReference(data: TextParserData): RelativeLink | undefined {
 }
 
 /**
- * Looks for `<a href="./relative">` and `<img src="./relative">`
+ * Looks for `<a href="./relative">`, `<img src="./relative">`, and `<source srcset="./relative">`
  */
-function checkTagLink(data: TextParserData): RelativeLink | undefined {
+function checkTagLink(data: TextParserData): RelativeLink[] {
     const { pos, token } = data;
 
     if (token.text.startsWith("<img ", pos)) {
         data.pos += 4;
-        return checkAttribute(data, "src");
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
+    }
+
+    if (token.text.startsWith("<link ", pos)) {
+        data.pos += 4;
+        return checkAttributes(data, {
+            imagesrcset: checkAttributeSrcSet,
+        });
     }
 
     if (token.text.startsWith("<a ", pos)) {
         data.pos += 3;
-        return checkAttribute(data, "href");
+        return checkAttributes(data, { href: checkAttributeDirectPath });
+    }
+
+    if (token.text.startsWith("<source ", pos)) {
+        data.pos += 8;
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
     }
+
+    return [];
 }
 
-function checkAttribute(
+function checkAttributes(
     data: TextParserData,
-    attr: string,
-): RelativeLink | undefined {
+    attributes: Record<
+        string,
+        (data: TextParserData, text: string, pos: number, end: number) => RelativeLink[]
+    >,
+): RelativeLink[] {
+    const links: RelativeLink[] = [];
     const parser = new HtmlAttributeParser(data.token.text, data.pos);
     while (parser.state !== ParserState.END) {
         if (
             parser.state === ParserState.BeforeAttributeValue &&
-            parser.currentAttributeName === attr
+            attributes.hasOwnProperty(parser.currentAttributeName)
         ) {
             parser.step();
 
-            if (isRelativePath(parser.currentAttributeValue)) {
-                data.pos = parser.pos;
-                const { target, anchor } = data.files.register(
-                    data.sourcePath,
-                    parser.currentAttributeValue as NormalizedPath,
-                ) || { target: undefined, anchor: undefined };
-                return {
-                    pos: parser.currentAttributeValueStart,
-                    end: parser.currentAttributeValueEnd,
-                    target,
-                    targetAnchor: anchor,
-                };
-            }
-            return;
+            links.push(...attributes[parser.currentAttributeName](
+                data,
+                parser.currentAttributeValue,
+                parser.currentAttributeValueStart,
+                parser.currentAttributeValueEnd,
+            ));
         }
 
         parser.step();
     }
+
+    return links;
+}
+
+function checkAttributeDirectPath(
+    data: TextParserData,
+    text: string,
+    pos: number,
+    end: number,
+): RelativeLink[] {
+    if (isRelativePath(text.trim())) {
+        const { target, anchor } = data.files.register(
+            data.sourcePath,
+            text.trim() as NormalizedPath,
+        ) || { target: undefined, anchor: undefined };
+        return [{
+            pos,
+            end,
+            target,
+            targetAnchor: anchor,
+        }];
+    }
+
+    return [];
+}
+
+// See https://html.spec.whatwg.org/multipage/images.html#srcset-attribute
+function checkAttributeSrcSet(data: TextParserData, text: string, pos: number, _end: number): RelativeLink[] {
+    const result: RelativeLink[] = [];
+
+    let textPos = 0;
+    parseImageCandidate();
+    while (textPos < text.length && text[textPos] == ",") {
+        ++textPos;
+        parseImageCandidate();
+    }
+
+    return result;
+
+    function parseImageCandidate() {
+        // 1. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos])) ++textPos;
+        // 2. A valid non-empty URL that does not start or end with a comma
+        // TypeDoc: We don't exactly match this, PR welcome! For now, just permit anything
+        // that's not whitespace or a comma
+        const url = text.slice(textPos).match(/^[^\t\r\f\n ,]+/);
+
+        if (url && isRelativePath(url[0])) {
+            const { target, anchor } = data.files.register(
+                data.sourcePath,
+                url[0] as NormalizedPath,
+            ) || { target: undefined, anchor: undefined };
+            result.push({
+                pos: pos + textPos,
+                end: pos + textPos + url[0].length,
+                target,
+                targetAnchor: anchor,
+            });
+        }
+        textPos += url ? url[0].length : 0;
+
+        // 3. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos])) ++textPos;
+
+        // 4. Zero or one of the following:
+        {
+            // A width descriptor, consisting of: ASCII whitespace, a valid non-negative integer giving
+            // a number greater than zero representing the width descriptor value, and a U+0077 LATIN
+            // SMALL LETTER W character.
+            const w = text.slice(textPos).match(/^\+?\d+\s*w/);
+            textPos += w ? w[0].length : 0;
+
+            // A pixel density descriptor, consisting of: ASCII whitespace, a valid floating-point number
+            // giving a number greater than zero representing the pixel density descriptor value, and a
+            // U+0078 LATIN SMALL LETTER X character.
+            if (!w) {
+                const x = text.slice(textPos).match(/^\+?\d+(\.\d+)?([eE][+-]\d+)?\s*x/);
+                textPos += x ? x[0].length : 0;
+            }
+        }
+
+        // 5. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos])) ++textPos;
+    }
 }
 
 function isRelativePath(link: string) {
diff --git a/src/test/comments.test.ts b/src/test/comments.test.ts
@@ -1630,6 +1630,148 @@ describe("Comment Parser", () => {
         );
     });
 
+    it("Recognizes HTML picture source srcset links", () => {
+        const comment = getComment(`/**
+        * <source media="(prefers-color-scheme: light)"  srcset="./test.png" >
+        * <source srcset="./test2.png 100w, ./test3.png 2x" >
+        * <source media="(prefers-color-scheme: dark)"  srcset="./test%20space.png, ./test5.png"/>
+        * <source srcset="https://example.com/favicon.ico">
+        */`);
+
+        equal(
+            comment.summary,
+            [
+                { kind: "text", text: '<source media="(prefers-color-scheme: light)"  srcset="' },
+                {
+                    kind: "relative-link",
+                    text: "./test.png",
+                    target: 1 as FileId,
+                    targetAnchor: undefined,
+                },
+                { kind: "text", text: '" >\n<source srcset="' },
+                {
+                    kind: "relative-link",
+                    text: "./test2.png",
+                    target: 2 as FileId,
+                    targetAnchor: undefined,
+                },
+                { kind: "text", text: " 100w, " },
+                {
+                    kind: "relative-link",
+                    text: "./test3.png",
+                    target: 3 as FileId,
+                    targetAnchor: undefined,
+                },
+                {
+                    kind: "text",
+                    text: ' 2x" >\n<source media="(prefers-color-scheme: dark)"  srcset="',
+                },
+                {
+                    kind: "relative-link",
+                    text: "./test%20space.png",
+                    target: 4 as FileId,
+                    targetAnchor: undefined,
+                },
+                {
+                    kind: "text",
+                    text: ", ",
+                },
+                {
+                    kind: "relative-link",
+                    text: "./test5.png",
+                    target: 5 as FileId,
+                    targetAnchor: undefined,
+                },
+                {
+                    kind: "text",
+                    text: '"/>\n<source srcset="https://example.com/favicon.ico">',
+                },
+            ] satisfies CommentDisplayPart[],
+        );
+    });
+
+    it("Recognizes <link imagesrcset> links", () => {
+        const comment = getComment(`/**
+        * <link imagesrcset="./test.png 100w" >
+        */`);
+
+        equal(
+            comment.summary,
+            [
+                { kind: "text", text: '<link imagesrcset="' },
+                {
+                    kind: "relative-link",
+                    text: "./test.png",
+                    target: 1 as FileId,
+                    targetAnchor: undefined,
+                },
+                { kind: "text", text: ' 100w" >' },
+            ] satisfies CommentDisplayPart[],
+        );
+    });
+
+    it("Recognizes HTML audio and video src links", () => {
+        const comment = getComment(`/**
+        * <source src="./test.wav" >
+        * <source media="(prefers-color-scheme: dark)" src="./test_dark.mp4"/>
+        * <source src="https://example.com/test.wav">
+        */`);
+
+        equal(
+            comment.summary,
+            [
+                { kind: "text", text: '<source src="' },
+                {
+                    kind: "relative-link",
+                    text: "./test.wav",
+                    target: 1 as FileId,
+                    targetAnchor: undefined,
+                },
+                { kind: "text", text: '" >\n<source media="(prefers-color-scheme: dark)" src="' },
+                {
+                    kind: "relative-link",
+                    text: "./test_dark.mp4",
+                    target: 2 as FileId,
+                    targetAnchor: undefined,
+                },
+                {
+                    kind: "text",
+                    text: '"/>\n<source src="https://example.com/test.wav">',
+                },
+            ] satisfies CommentDisplayPart[],
+        );
+    });
+
+    it("Recognizes img tag with both src and srcset", () => {
+        const comment = getComment(`/**
+        * <img src="./test.png" srcset="./test2.png">
+        */`);
+
+        equal(
+            comment.summary,
+            [
+                { kind: "text", text: '<img src="' },
+                {
+                    kind: "relative-link",
+                    text: "./test.png",
+                    target: 1 as FileId,
+                    targetAnchor: undefined,
+                },
+                { kind: "text", text: '" srcset="' },
+                {
+                    kind: "relative-link",
+                    text: "./test2.png",
+                    target: 2 as FileId,
+                    targetAnchor: undefined,
+                },
+                {
+                    kind: "text",
+                    text: '">',
+                },
+            ] satisfies CommentDisplayPart[],
+        );
+    });
+
     it("Recognizes HTML anchor links", () => {
         const comment = getComment(`/**
         * <a data-foo="./path.txt" href="./test.png" >
