Skip to content

fix(theme): remove jQuery dependency from static JS - #1607

Open
AMD-melliott wants to merge 4 commits into
ROCm:developfrom
AMD-melliott:melliott/fix-jquery-static-js
Open

fix(theme): remove jQuery dependency from static JS#1607
AMD-melliott wants to merge 4 commits into
ROCm:developfrom
AMD-melliott:melliott/fix-jquery-static-js

Conversation

@AMD-melliott

Copy link
Copy Markdown
Contributor

Issue

rocm_docs_theme's static JS — code_word_breaks.js, renameVersionLinks.js,
rdcMisc.js, and theme_mode_captions.js — references the jQuery global $,
but pydata-sphinx-theme (a rocm-docs-core dependency, currently pinned
>=0.15.4) hasn't shipped jQuery since it was dropped upstream in v0.13.0
(Feb 2023, [pydata/pydata-sphinx-theme#1029],
"Drop jQuery and use Bootstrap 5"). Every page load throws
ReferenceError: $ is not defined from all four files.

I noticed these errors when testing via Playwright-based console validation during the instinct-design flavor development.

Fix

Rewrote all four files to plain DOM APIs, no jQuery:

  • code_word_breaks.js / renameVersionLinks.js — mechanical translation to
    querySelectorAll/classList/native event listeners, same behavior.
  • rdcMisc.js — breadcrumb truncation math needed adjusting along the way:
    jQuery's .width()/.height() always normalized to content-box, while
    getComputedStyle() reflects box-sizing: border-box under
    pydata-sphinx-theme's Bootstrap 5 reset, which was inflating measured width
    and shifting the truncation threshold. Now computed via
    getBoundingClientRect() minus padding/border to match the original
    content-box semantics.
  • theme_mode_captions.js — drops the $(window).ajaxComplete(...) handler;
    there's no jQuery-driven AJAX left in this environment for it to observe,
    and the existing click listener already keeps the caption in sync on
    user-initiated theme toggles.

Scope / risk

A repo-wide check confirms these are the only four files in
rocm_docs_theme's own static assets referencing jQuery syntax — search.js
and the newer instinct-design.js are already jQuery-free. All four affected
behaviors are cosmetic UX affordances (code-cell copy + word-break
formatting, version-dropdown label cleanup, breadcrumb truncation + sidebar
auto-collapse, theme-toggle tooltip caption) — none touch search, navigation,
or content rendering, so functional risk from the rewrite is low.

A secondary bootstrap.js getBoundingClientRect TypeError reported
alongside this is from pydata-sphinx-theme's own vendored Bootstrap bundle,
not this theme's code — out of scope here; worth a separate upstream report
against pydata-sphinx-theme if it still reproduces once this lands.

Verification

Exercised via a standalone HTML harness with representative
breadcrumb/table/version-dropdown/theme-switch markup, run through Playwright
in a headless browser: zero console errors, and all four behaviors confirmed
working (click-to-copy, word-break insertion, breadcrumb truncation,
version-link renaming, theme-mode caption update).

AMD-melliott and others added 4 commits August 5, 2026 15:56
pydata-sphinx-theme dropped jQuery in v0.13.0 (Feb 2023,
pydata/pydata-sphinx-theme#1029), but rocm_docs_theme's static JS still
referenced the jQuery global $, throwing `ReferenceError: $ is not defined`
from code_word_breaks.js, renameVersionLinks.js, rdcMisc.js, and
theme_mode_captions.js on every page load.

Rewrote all four to plain DOM APIs (querySelectorAll, classList, native
event listeners):

- code_word_breaks.js / renameVersionLinks.js: mechanical translation, same
  behavior.
- rdcMisc.js: breadcrumb truncation math needed adjusting along the way.
  jQuery's .width()/.height() always normalized to content-box, while
  getComputedStyle() reflects box-sizing: border-box under
  pydata-sphinx-theme's Bootstrap 5 reset, inflating measured width and
  shifting the truncation threshold. Now computed via
  getBoundingClientRect() minus padding/border to match the original
  content-box semantics.
- theme_mode_captions.js: drops the $(window).ajaxComplete(...) handler;
  there's no jQuery-driven AJAX left in this environment for it to observe,
  and the existing click listener already keeps the caption in sync on
  user-initiated theme toggles.

A repo-wide check confirms these are the only four files in
rocm_docs_theme's own static assets referencing jQuery syntax; search.js
and instinct-design.js are already jQuery-free. All four affected
behaviors are cosmetic UX affordances (code-cell copy + word-break
formatting, version-dropdown label cleanup, breadcrumb truncation +
sidebar auto-collapse, theme-toggle tooltip caption) -- none touch search,
navigation, or content rendering, so functional risk is low.

Verified via a standalone HTML harness with representative
breadcrumb/table/version-dropdown/theme-switch markup, run through
Playwright in a headless browser: zero console errors, and all four
behaviors confirmed working.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.

1 participant