Allow more granular control over reflection icons

Author: Gerrit0

CHANGELOG.md

@@ -51,6 +51,7 @@ title: Changelog
 - Introduced `@function` tag to force TypeDoc to convert variable declarations with a type annotation as functions, #2881.
 - Exposed a `TypeDoc` global object in the HTML theme which can be used to prevent TypeDoc from using `localStorage`, #2872.
 - Introduced `@preventInline` and `@inlineType` tags for further control extending the `@inline` tag, #2862.
+- API: Introduced `DefaultThemeRenderContext.reflectionIcon` for more granular control over displayed reflection icons.
 
 ### Bug Fixes
 

src/lib/output/plugins/JavascriptIndexPlugin.ts

@@ -21,6 +21,7 @@ interface SearchDocument {
     url: string;
     classes?: string;
     parent?: string;
+    icon?: string | number;
 }
 
 /**
@@ -112,6 +113,11 @@ export class JavascriptIndexPlugin extends RendererComponent {
                 classes: theme.getReflectionClasses(reflection),
             };
 
+            const icon = theme.getReflectionIcon(reflection);
+            if (icon !== reflection.kind) {
+                row.icon = icon;
+            }
+
             if (parent) {
                 row.parent = parent.getFullName();
             }

src/lib/output/themes/default/DefaultTheme.tsx

@@ -27,6 +27,7 @@ export interface NavigationElement {
     kind?: ReflectionKind;
     class?: string;
     children?: NavigationElement[];
+    icon?: string | number;
 }
 
 /**
@@ -99,6 +100,13 @@ export class DefaultTheme extends Theme {
         return getReflectionClasses(reflection, filters);
     }
 
+    /**
+     * This is used so that themes may define multiple icons for modified icons (e.g. method, and inherited method)
+     */
+    getReflectionIcon(reflection: Reflection): keyof this["icons"] & (string | number) {
+        return reflection.kind;
+    }
+
     /**
      * Create a new DefaultTheme instance.
      *
@@ -176,12 +184,17 @@ export class DefaultTheme extends Theme {
                 };
             }
 
+            const icon = theme.getReflectionIcon(element) === element.kind
+                ? undefined
+                : theme.getReflectionIcon(element);
+
             return {
                 text: getDisplayName(element),
                 path: router.getFullUrl(element),
                 kind: element.kind & ReflectionKind.Project ? undefined : element.kind,
                 class: classNames({ deprecated: element.isDeprecated() }, theme.getReflectionClasses(element)),
                 children: children?.length ? children : undefined,
+                icon,
             };
         }
 

src/lib/output/themes/default/DefaultThemeRenderContext.ts

@@ -37,7 +37,7 @@ import { reflectionTemplate } from "./templates/reflection.js";
 import { typeDeclaration, typeDetails, typeDetailsIfUseful } from "./partials/typeDetails.js";
 import { moduleMemberSummary, moduleReflection } from "./partials/moduleReflection.js";
 import type { Router } from "../../router.js";
-import type { NeverIfInternal } from "#utils";
+import type { JSX, NeverIfInternal } from "#utils";
 
 function bind<F, L extends any[], R>(fn: (f: F, ...a: L) => R, first: F) {
     return (...r: L) => fn(first, ...r);
@@ -62,6 +62,9 @@ export class DefaultThemeRenderContext {
 
     /**
      * Icons available for use within the page.
+     * When getting an icon for a reflection, {@link reflectionIcon} should be used so
+     * that themes which define multiple icon variants can correctly specify which icon
+     * they want to be used.
      *
      * Note: This creates a reference to icons declared by {@link DefaultTheme.icons},
      * to customize icons, that object must be modified instead.
@@ -70,6 +73,13 @@ export class DefaultThemeRenderContext {
         return this._refIcons;
     }
 
+    /**
+     * Do not override this method, override {@link DefaultTheme.getReflectionIcon} instead.
+     */
+    reflectionIcon = (reflection: Reflection): JSX.Element => {
+        return this.icons[this.theme.getReflectionIcon(reflection)]();
+    };
+
     get slugger() {
         return this.router.getSlugger(this.page.model);
     }

src/lib/output/themes/default/assets/typedoc/Navigation.ts

@@ -6,6 +6,7 @@ export interface NavigationElement {
     kind?: number;
     class?: string;
     children?: NavigationElement[];
+    icon?: string | number;
 }
 
 let BASE_URL: string;
@@ -105,7 +106,9 @@ function addNavText(
                 """,
             );
             a.innerHTML =
-                `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon" aria-label="${label}"><use href="#icon-${el.kind}"></use></svg>`;
+                `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon" aria-label="${label}"><use href="#icon-${
+                    el.icon || el.kind
+                }"></use></svg>`;
         }
         a.appendChild(document.createElement("span")).textContent = el.text;
     } else {

src/lib/output/themes/default/assets/typedoc/components/Search.ts

@@ -16,6 +16,7 @@ interface SearchDocument {
     url: string;
     classes?: string;
     parent?: string;
+    icon?: string | number;
 }
 
 interface IData {
@@ -274,7 +275,9 @@ function updateResults(
             """,
         );
         const icon =
-            `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon" aria-label="${label}"><use href="#icon-${row.kind}"></use></svg>`;
+            `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon" aria-label="${label}"><use href="#icon-${
+                row.icon || row.kind
+            }"></use></svg>`;
 
         // Highlight the matched part of the query in the search results
         let name = highlightMatches(row.name, searchText);

src/lib/output/themes/default/partials/index.tsx

@@ -4,7 +4,7 @@ import { i18n, JSX } from "#utils";
 import type { ContainerReflection, ReflectionCategory, ReflectionGroup } from "../../../../models/index.js";
 
 function renderCategory(
-    { urlTo, icons, getReflectionClasses, markdown }: DefaultThemeRenderContext,
+    { urlTo, reflectionIcon, getReflectionClasses, markdown }: DefaultThemeRenderContext,
     item: ReflectionCategory | ReflectionGroup,
     prependName = "",
 ) {
@@ -26,7 +26,7 @@ function renderCategory(
                                 getReflectionClasses(item),
                             )}
                         >
-                            {icons[item.kind]()}
+                            {reflectionIcon(item)}
                             <span>{renderName(item)}</span>
                         </a>
                         {"\n"}

src/lib/output/themes/default/partials/moduleReflection.tsx

@@ -72,7 +72,7 @@ export function moduleMemberSummary(
 
         name = (
             <span class="tsd-member-summary-name">
-                {context.icons[target.kind]()}
+                {context.reflectionIcon(target)}
                 <span class={classNames({ deprecated: member.isDeprecated() })}>{member.name}</span>
                 <span>&nbsp;{"\u2192"}&nbsp;</span>
                 {uniqueName(context, target)}
@@ -82,7 +82,7 @@ export function moduleMemberSummary(
     } else {
         name = (
             <span class="tsd-member-summary-name">
-                {context.icons[member.kind]()}
+                {context.reflectionIcon(member)}
                 <a class={classNames({ deprecated: member.isDeprecated() })} href={context.urlTo(member)}>
                     {member.name}
                 </a>

src/lib/output/themes/default/templates/hierarchy.tsx

@@ -13,7 +13,7 @@ function fullHierarchy(
         return (
             <li data-refl={root.id}>
                 <a href={context.urlTo(root)}>
-                    {context.icons[root.kind]()}
+                    {context.reflectionIcon(root)}
                     {root.name}
                 </a>
             </li>
@@ -34,7 +34,7 @@ function fullHierarchy(
     return (
         <li data-refl={root.id} id={root.getFullName()}>
             <a href={context.urlTo(root)}>
-                {context.icons[root.kind]()}
+                {context.reflectionIcon(root)}
                 {root.name}
             </a>
             {children.length && <ul>{children}</ul>}

src/lib/utils-common/jsx.elements.ts

@@ -125,6 +125,7 @@ export interface IntrinsicElements {
     line: JsxLineElementProps;
     use: JsxUseElementProps;
     text: JsxTextElementProps;
+    image: JsxImageElementProps;
 }
 
 export function JsxFragment(): never {
@@ -1174,3 +1175,19 @@ export interface JsxTextElementProps extends JsxSvgCoreProps, JsxSvgStyleProps,
     x?: string | number;
     y?: string | number;
 }
+
+/**
+ * Properties permitted on the `<image>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/image
+ */
+export interface JsxImageElementProps extends JsxSvgCoreProps {
+    x?: string | number;
+    y?: string | number;
+    width?: string | number;
+    height?: string | number;
+    href: string;
+    preserveAspectRatio?: string;
+    crossorigin?: "anonymous" | "use-credentials";
+    decoding?: "async" | "sync" | "auto";
+}