Move code-term wrapping from a client enhancer to a rehype plugin (#61773)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/content-render/tests/render-content.ts

@@ -244,6 +244,57 @@ var a = 1
     // Generates a murmurhash based ID that matches a <pre>
   })
 
+  describe('wrap-code-terms (<wbr> in table code)', () => {
+    const table = (term: string) =>
+      nl(`
+| Term | Description |
+| --- | --- |
+| \`${term}\` | a long code term |
+`)
+
+    test('breaks camelCase code terms in tables', async () => {
+      const html = await renderContent(table('hasOrganizationProjects'))
+      const code = load(html)('td code').first()
+      expect(code.html()).toBe('has<wbr>Organization<wbr>Projects')
+    })
+
+    test('breaks long underscore code terms after the 12th character', async () => {
+      const html = await renderContent(table('has_organization_projects_enabled'))
+      const code = load(html)('td code').first()
+      expect(code.html()).toBe('has_organization_<wbr>projects_enabled')
+    })
+
+    test('breaks code terms separated by slashes', async () => {
+      const html = await renderContent(table('actions/checkout/setup-node'))
+      const code = load(html)('td code').first()
+      expect(code.html()).toBe('actions/<wbr>checkout/<wbr>setup-node')
+    })
+
+    test('leaves short code terms untouched', async () => {
+      const html = await renderContent(table('shortTerm'))
+      const code = load(html)('td code').first()
+      expect(code.html()).toBe('shortTerm')
+    })
+
+    test('does not insert <wbr> into code outside of tables', async () => {
+      const html = await renderContent(nl('Inline `hasOrganizationProjects` term.'))
+      expect(html).not.toContain('<wbr>')
+    })
+
+    test('breaks a code term whose text lives inside a child anchor', async () => {
+      const html = await renderContent(
+        nl(`
+| Term | Description |
+| --- | --- |
+| [\`hasOrganizationProjects\`](/foo) | a long code term |
+`),
+      )
+      const $ = load(html)
+      expect($('td a').attr('href')).toBe('/foo')
+      expect($('td a code').html()).toBe('has<wbr>Organization<wbr>Projects')
+    })
+  })
+
   test('renders alerts with data-container attribute for analytics', async () => {
     const template = nl(`
 > [!NOTE]

src/content-render/unified/processor.ts

@@ -26,6 +26,7 @@ import rewriteEmptyTableRows from './rewrite-empty-table-rows'
 import rewriteForRowheaders from './rewrite-for-rowheaders'
 import rewriteTableCaptions from './rewrite-table-captions'
 import wrapProceduralImages from './wrap-procedural-images'
+import wrapCodeTerms from './wrap-code-terms'
 import parseInfoString from './parse-info-string'
 import annotate from './annotate'
 import alerts from './alerts'
@@ -84,6 +85,7 @@ export function createProcessor(context: Context): UnifiedProcessor {
       .use(rewriteTheadThScope)
       .use(rewriteForRowheaders)
       .use(rewriteTableCaptions)
+      .use(wrapCodeTerms)
       .use(rewriteImgSources)
       .use(rewriteAssetImgTags)
       // alerts plugin requires context with alertTitles property

src/content-render/unified/wrap-code-terms.ts

@@ -0,0 +1,90 @@
+import type { Root, Element, Text, ElementContent, Parents } from 'hast'
+import { visitParents } from 'unist-util-visit-parents'
+import type { Transformer } from 'unified'
+
+// This plugin improves table rendering on reference pages by inserting a <wbr>
+// element into code terms that use camelcase, slashes, or underscores, inspired
+// by http://heap.ch/blog/2016/01/19/camelwrap/
+//
+// It runs server-side on the HTML AST so the break opportunities are present in
+// the rendered markup (both the HTML string and the hast that React renders),
+// rather than being mutated into the DOM imperatively on the client after
+// hydration. It only applies to `<code>` inside a `<table>`, matching the
+// previous client-side selector `#article-contents table code`.
+
+const wordsLongerThan18Chars = /[\S]{18,}/g
+const camelCaseChars = /([a-z])([A-Z])/g
+const underscoresAfter12thChar = /([\w:]{12}[^_]*?)_/g
+const slashChars = /([/\\])/g
+
+// A sentinel that cannot appear in source text; marks where a <wbr> goes.
+const WBR = '\u0000'
+
+function withBreakOpportunities(value: string): string {
+  return value.replace(wordsLongerThan18Chars, (str) =>
+    str
+      // GraphQL code terms use camelcase
+      .replace(camelCaseChars, `$1${WBR}$2`)
+      // REST code terms use underscores. To keep word breaks looking nice, only
+      // break on underscores after the 12th char so `has_organization_projects`
+      // breaks after `has_organization` instead of after `has_`.
+      .replace(underscoresAfter12thChar, `$1_${WBR}`)
+      // Some Actions reference pages have tables with code terms separated by slashes.
+      .replace(slashChars, `$1${WBR}`),
+  )
+}
+
+// A fresh <wbr> element per insertion, so inserted nodes never share the same
+// `properties`/`children` object references (which could be mutated later).
+function createWbrElement(): Element {
+  return { type: 'element', tagName: 'wbr', properties: {}, children: [] }
+}
+
+// Replace a text node's value with a sequence of text nodes interleaved with
+// <wbr> elements at each break opportunity. Returns null when nothing changed.
+function splitTextNode(node: Text): ElementContent[] | null {
+  const replaced = withBreakOpportunities(node.value)
+  if (!replaced.includes(WBR)) return null
+
+  const out: ElementContent[] = []
+  const parts = replaced.split(WBR)
+  for (const [index, part] of parts.entries()) {
+    if (part) out.push({ type: 'text', value: part })
+    if (index < parts.length - 1) out.push(createWbrElement())
+  }
+  return out
+}
+
+// Walk every descendant text node of `code`, inserting <wbr> elements in place.
+// This naturally handles the case where the code term's text lives inside a
+// child anchor element.
+function insertWordBreaks(code: Element): void {
+  const transform = (parent: Element): void => {
+    const next: ElementContent[] = []
+    for (const child of parent.children) {
+      if (child.type === 'text') {
+        const split = splitTextNode(child)
+        next.push(...(split ?? [child]))
+      } else {
+        if (child.type === 'element') transform(child)
+        next.push(child)
+      }
+    }
+    parent.children = next
+  }
+  transform(code)
+}
+
+function hasTableAncestor(ancestors: Parents[]): boolean {
+  return ancestors.some((ancestor) => ancestor.type === 'element' && ancestor.tagName === 'table')
+}
+
+export default function wrapCodeTerms(): Transformer<Root> {
+  return (tree: Root) =>
+    visitParents(tree, 'element', (node, ancestors) => {
+      const el = node as Element
+      if (el.tagName !== 'code') return
+      if (!hasTableAncestor(ancestors)) return
+      insertWordBreaks(el)
+    })
+}

src/frame/components/lib/wrap-code-terms.ts

@@ -18,7 +18,8 @@
 
     // We want to keep table-layout: auto so that column widths dynamically adjust;
     // otherwise entries get needlessly squashed into narrow columns. As a workaround,
-    // we use components/lib/wrap-code-terms.ts to prevent some reference table content
+    // we use the content-render/unified/wrap-code-terms.ts rehype plugin to prevent some
+    // reference table content
     // from expanding beyond the horizontal boundaries of the parent element.
     @media (min-width: 544px) {
       table-layout: auto;

src/frame/components/ui/MarkdownContent/stylesheets/table.scss

@@ -10,7 +10,6 @@ import type { JourneyTrack } from '@/journeys/lib/journey-path-resolver'
 // typically operating on elements **within** an article.
 import copyCode from '@/frame/components/lib/copy-code'
 import toggleAnnotation from '@/frame/components/lib/toggle-annotations'
-import wrapCodeTerms from '@/frame/components/lib/wrap-code-terms'
 
 import {
   MainContextT,
@@ -49,7 +48,6 @@ import { JourneyLanding } from '@/landings/components/journey/JourneyLanding'
 
 function initiateArticleScripts() {
   copyCode()
-  wrapCodeTerms()
   toggleAnnotation()
 }