feat(dom): jQuery wrapper scaffold + dom/query module (Step 1)#4399
Draft
elnelson575 wants to merge 15 commits into
Draft
feat(dom): jQuery wrapper scaffold + dom/query module (Step 1)#4399elnelson575 wants to merge 15 commits into
elnelson575 wants to merge 15 commits into
Conversation
Adds the design spec for wrapping Shiny's jQuery dependency behind a small set of capability-oriented modules (dom/query, dom/events, dom/html, dom/ajax, dom/widgets) with native + jQuery adapters and per-call dispatch. Includes the optional-peer-dependency model, the dual InputBinding/OutputBinding contract, build-time enforcement, testing strategy, migration order, and an outline of future widget replacements.
Rule 2: importing jquery or referencing JQuery<> types outside an adapter file fails the build. A '// shiny:jquery-allowed -- <reason>' magic comment exempts a file; exemptions are printed in an audit summary at the end of every build, so drift is visible. All currently-jquery-using source files are exempted with 'awaiting dom/* migration'; each follow-on plan removes its module's exemptions as it migrates.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First step of a long-term effort to wrap Shiny's jQuery usage behind a capability-oriented adapter layer. Lays the foundation; no user-facing API changes.
srcts/src/dom/wrapper. Capability modules with native + jQuery adapters and per-call dispatch (window.jQueryis checked at each call; native is used when absent).dom/query(select,closest,matches).JQueryRequiredErrorfor code paths that genuinely need jQuery and find it absent (infrastructure for follow-on modules; not yet thrown).srcts/build/_jquery.tsgains a second rule:import $ from "jquery"andJQuery<>type references are only allowed insrcts/src/dom/*/jquery.tsadapter files. A// shiny:jquery-allowed -- <reason>magic comment exempts pending files; every build prints a sorted audit of all 44 current exemptions so drift stays visible.$(document).find("[data-display-if]")inshinyapp.tsswitched toselect(document, "[data-display-if]"). Behavior preserved (dispatch picks jQuery in production).happy-domadded as devDep;setupDom()andwithJQuery()helpers enable dual-path adapter parity tests. New tests: 12 parity (6 × 2 adapters) + 1 explicit no-jQuery regression + smoke tests for helpers/errors.Design and plan are committed to the branch under
.claude/specs/and.claude/plans/.Out of scope for this PR (deferred to follow-on PRs):
dom/events,dom/html,dom/ajax,dom/widgets; the dualInputBinding/OutputBindingAPI; thepackage.jsonpeer-dependency switch; migration of the 43 remaining jquery-importing files (each carries the escape-hatch comment for now).Test plan
npm run checkspasses locally (lint, build_types, test_types, coverage, circular).npm run bundle_shinysucceeds and prints[_jquery audit] 44 file(s) carry shiny:jquery-allowed exemptions:at the end.npx tsx --test srcts/src/dom/query/__tests__/query.test.tsreports 12 passes (6 logical × 2 adapters).npx tsx --test srcts/src/dom/query/__tests__/query.no-jquery.test.tspasses withwindow.jQueryexplicitly asserted undefined.conditionalPanel()(which relies on thedata-display-ifselection we migrated) to confirm no regression in the conditional-show behavior.shiny:jquery-allowedcomment from any source file withimport $ from "jquery"and confirmnpm run bundle_shinyfails with the actionable Rule 2 error.Notes for reviewers
withJQuery()does not await async callbacks; the first follow-on plan (dom/events) will need to extend it before tests that useawaitwill work correctly. Surfaced in the final code review on this branch; not blocking this PR because no current code path is async.dom/widgetsfuture seam:JQueryRequiredErroris the contract that the eventualdom/widgetsmodule (jQuery-plugin widgets — datepicker, ion-rangeslider, selectize, DataTables) will throw when jQuery is absent. Defined here so adapter authors can rely on it.shinyapp.tsis intentionally narrow — the goal is to prove the dispatch works end-to-end, not to drain the queue.