Label icon SVGs

Resolves #2832

Author: Gerrit0

CHANGELOG.md

@@ -11,6 +11,7 @@ title: Changelog
 ### Bug Fixes
 
 -   Fixed an issue where TypeDoc would incorrectly ignore type arguments in references, #2823.
+-   Improved narrator support for labeling icons, #2832.
 
 ## v0.27.6 (2024-12-26)
 

src/index.ts

@@ -63,6 +63,7 @@ export type {
     NavigationElement,
     RendererEvents,
     PageHeading,
+    Icons,
 } from "./lib/output/index.js";
 
 export { Outputs } from "./lib/output/output.js";

src/lib/internationalization/locales/en.cts

@@ -512,10 +512,12 @@ export = {
     theme_search: "Search",
     theme_menu: "Menu",
     theme_permalink: "Permalink",
+    theme_folder: "Folder",
 
     // Used by the frontend JS
     // For the English translations only, these should also be added to
     // src/lib/output/themes/default/assets/typedoc/Application.ts
+    // Also uses theme_folder and singular kinds
     theme_copy: "Copy",
     theme_copied: "Copied!",
     theme_normally_hidden:

src/lib/output/index.ts

@@ -16,3 +16,4 @@ export {
 } from "./themes/default/DefaultTheme.js";
 export { Slugger } from "./themes/default/Slugger.js";
 export { DefaultThemeRenderContext } from "./themes/default/DefaultThemeRenderContext.js";
+export type { Icons } from "./themes/default/partials/icon.js";

src/lib/output/plugins/AssetsPlugin.ts

@@ -3,11 +3,12 @@ import { RendererEvent } from "../events.js";
 import { copySync, readFile, writeFileSync } from "../../utils/fs.js";
 import { DefaultTheme } from "../themes/default/DefaultTheme.js";
 import { getStyles } from "../../utils/highlighter.js";
-import { Option } from "../../utils/index.js";
+import { getEnumKeys, Option, type EnumKeys } from "../../utils/index.js";
 import { existsSync } from "fs";
 import { extname, join } from "path";
 import { fileURLToPath } from "url";
 import type { Renderer } from "../index.js";
+import { ReflectionKind } from "../../models/index.js";
 
 /**
  * A plugin that copies the subdirectory ´assets´ from the current themes
@@ -30,14 +31,24 @@ export class AssetsPlugin extends RendererComponent {
     }
 
     getTranslatedStrings() {
-        return {
-            copy: this.application.i18n.theme_copy(),
-            copied: this.application.i18n.theme_copied(),
-            normally_hidden: this.application.i18n.theme_normally_hidden(),
-            hierarchy_expand: this.application.i18n.theme_hierarchy_expand(),
-            hierarchy_collapse:
-                this.application.i18n.theme_hierarchy_collapse(),
+        const inter = this.application.internationalization;
+        const i18n = this.application.i18n;
+
+        const translations: Record<string, string> = {
+            copy: i18n.theme_copy(),
+            copied: i18n.theme_copied(),
+            normally_hidden: i18n.theme_normally_hidden(),
+            hierarchy_expand: i18n.theme_hierarchy_expand(),
+            hierarchy_collapse: i18n.theme_hierarchy_collapse(),
+            folder: i18n.theme_folder(),
         };
+
+        for (const key of getEnumKeys(ReflectionKind)) {
+            const kind = ReflectionKind[key as EnumKeys<typeof ReflectionKind>];
+            translations[`kind_${kind}`] = inter.kindSingularString(kind);
+        }
+
+        return translations;
     }
 
     private onRenderBegin(event: RendererEvent) {

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

@@ -19,7 +19,7 @@ import type { MarkedPlugin } from "../../plugins/index.js";
 import { DefaultThemeRenderContext } from "./DefaultThemeRenderContext.js";
 import { filterMap, JSX, Option, type TypeDocOptionMap } from "../../../utils/index.js";
 import { classNames, getDisplayName, getHierarchyRoots, toStyleClass } from "../lib.js";
-import { icons } from "./partials/icon.js";
+import { getIcons, type Icons } from "./partials/icon.js";
 import { Slugger } from "./Slugger.js";
 import { createNormalizedUrl } from "../../../utils/html.js";
 
@@ -77,7 +77,7 @@ export class DefaultTheme extends Theme {
      * the icons used within the page, however TypeDoc currently assumes that all icons are svg
      * elements, so custom themes must also use svg elements.
      */
-    icons = { ...icons };
+    icons: Icons;
 
     getRenderContext(pageEvent: PageEvent<Reflection>) {
         return new DefaultThemeRenderContext(this, pageEvent, this.application.options);
@@ -159,6 +159,7 @@ export class DefaultTheme extends Theme {
      */
     constructor(renderer: Renderer) {
         super(renderer);
+        this.icons = getIcons(renderer.application.i18n);
         this.markedPlugin = renderer.markedPlugin;
     }
 

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

@@ -24,7 +24,7 @@ import {
 import { footer } from "./partials/footer.js";
 import { header } from "./partials/header.js";
 import { hierarchy } from "./partials/hierarchy.js";
-import { buildRefIcons, type icons } from "./partials/icon.js";
+import { buildRefIcons, type Icons } from "./partials/icon.js";
 import { member } from "./partials/member.js";
 import { memberDeclaration } from "./partials/member.declaration.js";
 import { memberGetterSetter } from "./partials/member.getterSetter.js";
@@ -65,7 +65,7 @@ function bind<F, L extends any[], R>(fn: (f: F, ...a: L) => R, first: F) {
 }
 
 export class DefaultThemeRenderContext {
-    private _refIcons: typeof icons;
+    private _refIcons: Icons;
     options: Options;
     internationalization: Internationalization;
     i18n: TranslationProxy;
@@ -87,7 +87,7 @@ export class DefaultThemeRenderContext {
      * Note: This creates a reference to icons declared by {@link DefaultTheme.icons},
      * to customize icons, that object must be modified instead.
      */
-    get icons(): Readonly<typeof icons> {
+    get icons(): Readonly<Icons> {
         return this._refIcons;
     }
 

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

@@ -8,6 +8,10 @@ declare global {
             normally_hidden: string;
             hierarchy_expand: string;
             hierarchy_collapse: string;
+
+            // Kind strings for icons
+            folder: string;
+            [k: `kind_${number}`]: string;
         };
     }
 }
@@ -20,6 +24,32 @@ window.translations ||= {
         "This member is normally hidden due to your filter settings.",
     hierarchy_expand: "Expand",
     hierarchy_collapse: "Collapse",
+
+    folder: "Folder",
+    kind_1: "Project",
+    kind_2: "Module",
+    kind_4: "Namespace",
+    kind_8: "Enumeration",
+    kind_16: "Enumeration Member",
+    kind_32: "Variable",
+    kind_64: "Function",
+    kind_128: "Class",
+    kind_256: "Interface",
+    kind_512: "Constructor",
+    kind_1024: "Property",
+    kind_2048: "Method",
+    kind_4096: "Call Signature",
+    kind_8192: "Index Signature",
+    kind_16384: "Constructor Signature",
+    kind_32768: "Parameter",
+    kind_65536: "Type Literal",
+    kind_131072: "Type Parameter",
+    kind_262144: "Accessor",
+    kind_524288: "Get Signature",
+    kind_1048576: "Set Signature",
+    kind_2097152: "Type Alias",
+    kind_4194304: "Reference",
+    kind_8388608: "Document",
 };
 
 /**

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

@@ -98,12 +98,17 @@ function addNavText(
             a.classList.add("current");
         }
         if (el.kind) {
-            a.innerHTML = `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon"><use href="#icon-${el.kind}"></use></svg>`;
+            const label = window.translations[`kind_${el.kind}`].replaceAll(
+                '"',
+                "&quot;",
+            );
+            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>`;
         }
         a.appendChild(document.createElement("span")).textContent = el.text;
     } else {
         const span = parent.appendChild(document.createElement("span"));
-        span.innerHTML = `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon"><use href="#icon-folder"></use></svg>`;
+        const label = window.translations.folder.replaceAll('"', "&quot;");
+        span.innerHTML = `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon" aria-label="${label}"><use href="#icon-folder"></use></svg>`;
         span.appendChild(document.createElement("span")).textContent = el.text;
     }
 }