fix(docs-infra): add target="_blank" to external links in @see JSDoc tags

External links rendered via `@see {@link ...}` and `@see [label](url)`
were not opening in a new tab. The `getHtmlAdditionalLinks` function
now sets `target: '_blank'` on `LinkEntryRenderable` objects whose URL
is external, and `docs-pill-row.tsx` passes the `target` attribute to
the rendered anchor tag.

Fixes: angular#69593

Author: MeAkib

adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts

@@ -149,6 +149,7 @@ export interface LinkEntryRenderable {
   label: string;
   url: string;
   title?: string;
+  target?: string;
 }
 
 export type CliOptionRenderable = CliOption & {

adev/shared-docs/pipeline/api-gen/rendering/templates/docs-pill-row.tsx

@@ -20,6 +20,7 @@ export function DocsPillRow(props: {links: LinkEntryRenderable[]}) {
           class="docs-pill"
           href={link.url}
           title={link.title}
+          target={link.target}
           dangerouslySetInnerHTML={{__html: link.label}}
         ></a>
       ))}

adev/shared-docs/pipeline/api-gen/rendering/test/transforms/jsdoc-transforms.spec.mts

@@ -89,58 +89,70 @@ describe('jsdoc transforms', () => {
         label: 'Angular',
         url: 'https://angular.io',
         title: undefined,
+        target: '_blank',
       });
 
       expect(entry.additionalLinks[1]).toEqual({
         label: 'Angular',
         url: 'https://angular.io',
         title: 'Angular',
+        target: '_blank',
       });
 
       expect(entry.additionalLinks[2]).toEqual({
         label: 'Route',
         url: '/api/test/Route',
+        target: undefined,
       });
 
       expect(entry.additionalLinks[3]).toEqual({
         label: 'Something else',
         url: '/api/test/Route',
+        target: undefined,
       });
 
       expect(entry.additionalLinks[4]).toEqual({
         label: 'someMethod',
         url: '/api/test/Router#someMethod',
+        target: undefined,
       });
       expect(entry.additionalLinks[5]).toEqual({
         label: 'someMethodWithParenthesis()',
         url: '/api/test/Router#someMethodWithParenthesis',
+        target: undefined,
       });
       expect(entry.additionalLinks[6]).toEqual({
         label: 'someMethod()',
         url: '/api/test/Router#someMethod',
+        target: undefined,
       });
       expect(entry.additionalLinks[7]).toEqual({
         label: 'FormGroup.someMethod()',
         url: '/api/test/FormGroup#someMethod',
+        target: undefined,
       });
 
       expect(entry.additionalLinks[8]).toEqual({
         label: 'ApplicationRef',
         url: 'https://angular.dev/api/core/ApplicationRef',
+        target: '_blank',
       });
       expect(entry.additionalLinks[9]).toEqual({
         label: 'angular.dev',
         url: 'https://angular.dev',
+        target: '_blank',
       });
 
       expect(entry.additionalLinks[10]).toEqual({
         label: 'ng build',
         url: '/cli/build',
+        target: undefined,
       });
 
       expect(entry.additionalLinks[11]).toEqual({
         label: 'Output Interop',
         url: '/ecosystem/rxjs-interop/output-interop',
+        target: undefined,
       });
     });
 
@@ -176,12 +188,14 @@ describe('jsdoc transforms', () => {
           'Popup attached to <code>document.body</code> with <code>createComponent</code> + <code>hostElement</code>',
         url: 'guide/components/programmatic-rendering#popup-attached-to-documentbody-with-createcomponent--hostelement',
         title: undefined,
+        target: undefined,
       });
 
       expect(entry.additionalLinks[2]).toEqual({
         label: 'Method with <code>backticks</code> in title',
         url: 'https://example.com',
         title: 'Title with `code`',
+        target: '_blank',
       });
     });
 

adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts

@@ -34,6 +34,7 @@ import {
   unknownSymbolMessage,
 } from '../symbol-context.mjs';
 import {addApiLinksToHtml} from './code-transforms.mjs';
+import {isExternalLink} from '../../../shared/marked/helpers.mjs';
 
 const JS_DOC_USAGE_NOTE_TAGS: Set<string> = new Set(['remarks', 'usageNotes', 'example']);
 export const JS_DOC_SEE_TAG = 'see';
@@ -144,17 +145,19 @@ function getHtmlAdditionalLinks<T extends HasJsDocTags>(entry: T): LinkEntryRend
   const seeAlsoLinks = entry.jsdocTags
     .filter((tag) => tag.name === JS_DOC_SEE_TAG)
     .map((tag) => tag.comment)
-    .map((comment) => {
+    .map((comment): LinkEntryRenderable | undefined => {
       // TODO: Throw when the comment is an absolute link.
       // With TS 5.9 this is not possible as the ts api that extracts comments from tags strips the "http" part of links.
 
       const markdownLinkMatch = comment.match(markdownLinkRule);
 
       if (markdownLinkMatch) {
+        const url = markdownLinkMatch[2];
         return {
           label: convertBackticksToCodeTags(markdownLinkMatch[1]),
-          url: markdownLinkMatch[2],
+          url,
           title: markdownLinkMatch[3],
+          target: isExternalLink(url) ? '_blank' : undefined,
         };
       }
 
@@ -163,11 +166,9 @@ function getHtmlAdditionalLinks<T extends HasJsDocTags>(entry: T): LinkEntryRend
       if (linkMatch) {
         const link = linkMatch[1];
         const parsed = parseAtLink(link);
-        if (!parsed) {
-          return undefined;
-        }
+        if (!parsed) return undefined;
         const {url, label} = parsed;
-        return {label, url};
+        return {label, url, target: isExternalLink(url) ? '_blank' : undefined};
       }
 
       return undefined;