Break navigation lines

Resolves #2940

Author: Gerrit0

CHANGELOG.md

@@ -6,6 +6,7 @@ title: Changelog
 
 ### Features
 
+- The navigation in the default theme will now attempt to break long names onto multiple lines, #2940.
 - Added German (de) localization, #2941.
 
 ### Bug Fixes

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

@@ -110,12 +110,30 @@ function addNavText(
                     el.icon || el.kind
                 }"></use></svg>`;
         }
-        a.appendChild(document.createElement("span")).textContent = el.text;
+        a.appendChild(wbr(el.text, document.createElement("span")));
     } else {
         const span = parent.appendChild(document.createElement("span"));
         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;
+        span.appendChild(wbr(el.text, document.createElement("span")));
     }
 }
+
+function wbr(str: string, element: HTMLElement) {
+    // Keep this in sync with the same helper in lib.tsx
+    // We use lookahead/lookbehind to indicate where the string should
+    // be split without consuming a character.
+    // (?<=[^A-Z])(?=[A-Z]) -- regular camel cased text
+    // (?<=[A-Z])(?=[A-Z][a-z]) -- acronym
+    // (?<=[_-])(?=[^_-]) -- snake
+    const parts = str.split(/(?<=[^A-Z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|(?<=[_-])(?=[^_-])/);
+    for (let i = 0; i < parts.length; ++i) {
+        if (i !== 0) {
+            element.appendChild(document.createElement("wbr"));
+        }
+        element.appendChild(document.createTextNode(parts[i]));
+    }
+
+    return element;
+}

src/lib/output/themes/lib.tsx

@@ -49,18 +49,14 @@ export function getKindClass(refl: Reflection): string {
  * @return The original string containing ``<wbr>`` tags where possible.
  */
 export function wbr(str: string): (string | JSX.Element)[] {
-    // TODO surely there is a better way to do this, but I'm tired.
-    const ret: (string | JSX.Element)[] = [];
-    const re = /[\s\S]*?(?:[^_-][_-](?=[^_-])|[^A-Z](?=[A-Z][^A-Z]))/g;
-    let match: RegExpExecArray | null;
-    let i = 0;
-    while ((match = re.exec(str))) {
-        ret.push(match[0], <wbr />);
-        i += match[0].length;
-    }
-    ret.push(str.slice(i));
-
-    return ret;
+    // Keep this in sync with the same helper in Navigation.ts
+    // We use lookahead/lookbehind to indicate where the string should
+    // be split without consuming a character.
+    // (?<=[^A-Z])(?=[A-Z]) -- regular camel cased text
+    // (?<=[A-Z])(?=[A-Z][a-z]) -- acronym
+    // (?<=[_-])(?=[^_-]) -- snake
+    const parts = str.split(/(?<=[^A-Z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|(?<=[_-])(?=[^_-])/);
+    return parts.flatMap(p => [p, <wbr />]).slice(0, -1);
 }
 
 export function join<T>(joiner: JSX.Children, list: readonly T[], cb: (x: T) => JSX.Children) {

src/test/output/lib.test.tsx

@@ -0,0 +1,28 @@
+import { deepStrictEqual as equal } from "node:assert";
+import { wbr } from "../../lib/output/themes/lib.js";
+import { JSX } from "#utils";
+
+describe("wbr", () => {
+    it("No breaks", () => {
+        equal(wbr("hello"), ["hello"]);
+    });
+
+    it("Adds <wbr> to camelCased text", () => {
+        equal(wbr("helloWorld"), ["hello", <wbr />, "World"]);
+        equal(wbr("helloWorldMulti"), ["hello", <wbr />, "World", <wbr />, "Multi"]);
+    });
+
+    it("Adds <wbr> to snake_cased text", () => {
+        equal(wbr("snake_case_text"), ["snake_", <wbr />, "case_", <wbr />, "text"]);
+        equal(wbr("snake__case__text"), ["snake__", <wbr />, "case__", <wbr />, "text"]);
+    });
+
+    it("Adds <wbr> to dashed-text", () => {
+        equal(wbr("dashed-text"), ["dashed-", <wbr />, "text"]);
+    });
+
+    it("Adds <wbr> appropriately with acronyms", () => {
+        equal(wbr("HTMLImageElement"), ["HTML", <wbr />, "Image", <wbr />, "Element"]);
+        equal(wbr("theHTMLImageElement"), ["the", <wbr />, "HTML", <wbr />, "Image", <wbr />, "Element"]);
+    });
+});