Skip to content

fix(docs[spa]): Fix prompt copy buttons surviving SPA navigation#5

Draft
tony wants to merge 1 commit intomainfrom
doc-redesign-spring-2026-2
Draft

fix(docs[spa]): Fix prompt copy buttons surviving SPA navigation#5
tony wants to merge 1 commit intomainfrom
doc-redesign-spring-2026-2

Conversation

@tony
Copy link
Copy Markdown
Member

@tony tony commented Mar 28, 2026

Summary

  • Fix prompt copy buttons breaking after SPA navigation
  • Replace clone-based button creation with inline HTML template matching sphinx-copybutton's exact output
  • Switch prompt-copy.js from direct event binding to document-level event delegation (capture phase)
  • Match sphinx-copybutton's exact success feedback (green checkmark SVG swap + staggered timeouts)

Root causes fixed

  1. No buttons after SPA nav from index.html: addCopyButtons() cloned an existing .copybtn as template — but index.html has no code blocks, so the template was always null when landing there first. Replaced with inline HTML template.

  2. Prompt blocks skipped: addCopyButtons() only created buttons for div.highlight pre (code blocks), not div.admonition.prompt > p:last-child (prompts). Added prompt block handling.

  3. Event listeners destroyed by DOM swap: prompt-copy.js used direct addEventListener on each button — destroyed when SPA navigation replaced .article-container. Switched to document-level event delegation in capture phase.

  4. Wrong button detection selector: .closest("div.admonition.prompt .copybtn") assumed button was a descendant of the prompt div. sphinx-copybutton inserts buttons via insertAdjacentHTML('afterend') making them siblings. Fixed by checking where data-clipboard-target points instead.

  5. Missing success feedback: prompt-copy.js only did tooltip+class, not the SVG icon swap to green checkmark. Now matches sphinx-copybutton's exact behavior.

Test plan

  • Load index.html, SPA-navigate to Quickstart via sidebar — copy buttons appear on all code blocks and prompt blocks
  • Click a prompt copy button with inline code — green checkmark appears, clipboard contains markdown with backticks
  • SPA-navigate away and back — prompt copy buttons still work
  • Direct-load a page with prompts (e.g. /recipes/) — copy buttons work on first load
  • Code block copy buttons still work identically before and after SPA nav

why: Prompt copy buttons broke after SPA navigation due to three
compounding issues: (1) addCopyButtons() only created buttons for code
blocks, not prompt blocks, (2) it cloned an existing button as template
which failed when landing on pages without code blocks (e.g. index.html),
(3) prompt-copy.js used direct event binding destroyed by DOM swaps.
what:
- spa-nav.js: Replace clone-based button creation with inline HTML
  template matching sphinx-copybutton's exact output (SVG + classes)
- spa-nav.js: Add prompt block button creation alongside code blocks
- prompt-copy.js: Switch from direct binding to document-level event
  delegation (capture phase) — survives DOM swaps
- prompt-copy.js: Detect prompt buttons by checking data-clipboard-target
  points into .admonition.prompt, not by button DOM ancestry (buttons
  are siblings, not descendants, of the prompt div)
- prompt-copy.js: Match sphinx-copybutton's exact success feedback
  (green checkmark SVG swap + staggered tooltip/class timeouts)
- Add console.warn for error paths instead of silent returns
@codecov-commenter
Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.10%. Comparing base (ee213d1) to head (d36cb1c).

Additional details and impacted files
@@           Coverage Diff           @@
##             main       #5   +/-   ##
=======================================
  Coverage   71.10%   71.10%           
=======================================
  Files          20       20           
  Lines        1419     1419           
  Branches      186      186           
=======================================
  Hits         1009     1009           
  Misses        365      365           
  Partials       45       45           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants