Add tooltip to footnote return icon on markdown pages

Author: webstackdev

src/lib/markdown/__tests__/e2e/rehype-footnotes-title.spec.tsx

@@ -25,11 +25,16 @@ afterEach(() => {
 })
 
 describe('Layer 3: E2E - rehypeFootnotesTitle', () => {
-  it('should add a title attribute to footnote backrefs', () => {
+  it('should wrap footnote backrefs in explicit tooltip markup', () => {
     const { container } = render(<MarkdownOutput html={html} />)
 
+    const tooltip = container.querySelector('site-tooltip')
     const backref = container.querySelector('a[data-footnote-backref]')
+    const popup = container.querySelector('[data-tooltip-popup]')
+
+    expect(tooltip).toBeTruthy()
     expect(backref).toBeTruthy()
-    expect(backref?.getAttribute('title')).toBe('Return to footnote 1')
+    expect(backref?.getAttribute('title')).toBeNull()
+    expect(popup?.textContent).toBe('Return to footnote 1')
   })
 })

src/lib/markdown/__tests__/integration/rehype-footnotes-title-astro.spec.ts

@@ -4,7 +4,7 @@ import { processWithAstroSettings } from '@lib/markdown/helpers/processors'
 import { rehypeFootnotesTitleConfig } from '@lib/config/markdown'
 
 describe('rehype-footnotes-title (Layer 2: With Astro Pipeline)', () => {
-  it('should add a title attribute to footnote backrefs', async () => {
+  it('should wrap footnote backrefs in explicit tooltip markup', async () => {
     const markdown = `Here is a footnote.[^1]
 
 [^1]: My reference.`
@@ -16,8 +16,12 @@ describe('rehype-footnotes-title (Layer 2: With Astro Pipeline)', () => {
       stage: 'rehype',
     })
 
+    expect(html).toContain('<site-tooltip')
     expect(html).toContain('data-footnote-backref')
-    expect(html).toContain('title="Return to footnote 1"')
+    expect(html).toContain('data-tooltip-trigger')
+    expect(html).toContain('data-tooltip-popup')
+    expect(html).toContain('Return to footnote 1')
+    expect(html).not.toContain('title="Return to footnote 1"')
   })
 
   it('should set aria-labelledby on the footnotes section', async () => {

src/lib/markdown/plugins/rehype-footnotes-title/__tests__/index.spec.ts

@@ -4,7 +4,7 @@ import { rehypeFootnotesTitleConfig } from '@lib/config/markdown'
 import { processIsolated } from '@lib/markdown/helpers/processors'
 
 describe('rehype-footnotes-title (Layer 1: Isolated)', () => {
-  it('should add title attribute to footnote backrefs', async () => {
+  it('should wrap footnote backrefs in explicit tooltip markup', async () => {
     const markdown = `Here is a footnote.[^1]
 
 [^1]: My reference.`
@@ -17,8 +17,12 @@ describe('rehype-footnotes-title (Layer 1: Isolated)', () => {
       gfm: true,
     })
 
+    expect(html).toContain('<site-tooltip')
     expect(html).toContain('data-footnote-backref')
-    expect(html).toContain('title="Return to footnote 1"')
+    expect(html).toContain('data-tooltip-trigger')
+    expect(html).toContain('data-tooltip-popup')
+    expect(html).toContain('Return to footnote 1')
+    expect(html).not.toContain('title="Return to footnote 1"')
   })
 
   it('should not add title attribute to footnote references', async () => {

src/lib/markdown/plugins/rehype-footnotes-title/index.ts

@@ -1,8 +1,37 @@
-import { visit } from 'unist-util-visit'
-import type { Root, Element, ElementContent, Text } from 'hast'
+import { SKIP, visit } from 'unist-util-visit'
+import type { Root, Element, ElementContent, Text, Properties } from 'hast'
 
 const FOOTNOTES_HEADING_TEXT = 'Footnotes'
 const FOOTNOTES_HEADING_ID = 'footnote-label'
+const TOOLTIP_HOST_CLASSES = ['relative', 'inline-flex']
+const TOOLTIP_TRIGGER_CLASSES = [
+  'inline-flex',
+  'items-center',
+  'focus-visible:outline-2',
+  'focus-visible:outline-offset-2',
+  'focus-visible:outline-spotlight',
+]
+const TOOLTIP_POPUP_CLASSES = [
+  'pointer-events-none',
+  'absolute',
+  'left-0',
+  'top-full',
+  'z-(--z-content-floating)',
+  'mt-2',
+  'hidden',
+  'max-w-64',
+  'rounded-md',
+  'border',
+  'border-trim',
+  'bg-page-inverse',
+  'px-2',
+  'py-1',
+  'text-sm',
+  'leading-tight',
+  'text-page-base',
+  'shadow-elevated',
+  'whitespace-nowrap',
+]
 
 function isElementNode(node: ElementContent): node is Element {
   return node.type === 'element'
@@ -86,6 +115,49 @@ function buildTitle(template: string, identifier: string): string {
   return template.includes('$id') ? template.replaceAll('$id', identifier) : template
 }
 
+function removeTooltipProperties(properties: Properties): Properties {
+  const nextProperties: Properties = { ...properties }
+  delete nextProperties['data-tooltip']
+  delete nextProperties['title']
+  return nextProperties
+}
+
+function wrapBackrefWithTooltip(node: Element, title: string): void {
+  const anchorNode: Element = {
+    type: 'element',
+    tagName: 'a',
+    properties: removeTooltipProperties(node.properties || {}),
+    children: node.children,
+  }
+
+  node.tagName = 'site-tooltip'
+  node.properties = {
+    className: TOOLTIP_HOST_CLASSES,
+  }
+  node.children = [
+    {
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        'data-tooltip-trigger': '',
+        className: TOOLTIP_TRIGGER_CLASSES,
+      },
+      children: [anchorNode],
+    },
+    {
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        'data-tooltip-popup': '',
+        role: 'tooltip',
+        'aria-hidden': 'true',
+        className: TOOLTIP_POPUP_CLASSES,
+      },
+      children: [{ type: 'text', value: title }],
+    },
+  ]
+}
+
 export type RehypeFootnotesTitleOptions = string
 
 export function rehypeFootnotesTitle(titleTemplate: RehypeFootnotesTitleOptions = '') {
@@ -110,8 +182,8 @@ export function rehypeFootnotesTitle(titleTemplate: RehypeFootnotesTitleOptions
       const identifier = getIdentifierFromBackrefHref(properties['href'])
       if (!identifier) return
 
-      properties['title'] = buildTitle(titleTemplate, identifier)
-      node.properties = properties
+      wrapBackrefWithTooltip(node, buildTitle(titleTemplate, identifier))
+      return SKIP
     })
   }
 }