Repository navigation
paginationNav() silently discards unknown arguments #2717
Description
Severity: low — discoverability gap.
Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.
Description
paginationNav() builds a local.subArgs struct by skipping a fixed list of its own argument names and copying everything else through to its sub-helpers (firstPageLink, previousPageLink, pageNumberLinks, nextPageLink, lastPageLink). When an arg doesn't match any sub-helper's accepted args, it's silently dropped — no error, no warning, no log.
Example: passing windowSize=3 works (it goes to pageNumberLinks). Passing divider=\" / \" works on the page-number primitive. Passing something like prependToList=\"<ul>\" does nothing — no error, but the user has no signal that the arg was rejected.
Why this matters
Users coming from paginationLinks() have muscle memory for arg names that no longer apply. Without a signal that those args were ignored, debugging styling issues becomes "is this arg working? let me try a different value… still doesn't work… is the value being applied at all?"
Suggested fix
At the bottom of paginationNav()'s arg fan-out, if any arg in arguments didn't get consumed by a sub-helper, log a warning:
if (StructCount(local.unconsumedArgs)) {
DeprecationLogger.log(message=\"paginationNav: ignored args [#StructKeyList(local.unconsumedArgs)#]\");
}Or fail fast in development environment, warn in production.
cc @bpamiri
Activity
wheels-bot commentedon May 15, 2026
Wheels Bot — Triage
Classified as bug.
Suspected layer
view— see.ai/wheels/views/for canonical patterns. The pagination helpers live invendor/wheels/view/pagination.cfc.Fix sketch
The fan-out lives at
vendor/wheels/view/pagination.cfc:347-356—paginationNav()buildslocal.subArgsby skipping its own named args and copying the rest into a struct that's passed viaargumentCollectionto every sub-helper. The sub-helpers (paginationInfo,firstPageLink,previousPageLink,pageNumberLinks,nextPageLink,lastPageLink) each have their own$args(name=...)registration that defines what they accept. Any key insubArgsthat isn't accepted by any sub-helper is silently dropped.Fix shape: after the fan-out loop, compute the union of each sub-helper's accepted argument names (lookup via the same
$argsregistry the helpers themselves use), diff against the passed-through keys, and emit a one-time warning for the leftover set. Wheels has no centralDeprecationLoggerclass (the report's snippet is illustrative); the existing pattern is an ad-hoclog()call or pushing onto a warnings array — seevendor/wheels/Plugins.cfc:556-564for the closest precedent. Behavior choice (warn always vs warn-in-dev/throw-in-dev) is the main design call.Confidence:
mediumLayer and target file are unambiguous, but the fix has real design trade-offs (warn vs throw, dev-only vs all envs, how to enumerate each sub-helper's accepted args without hard-coding) that propose-fix needs to resolve.
<!-- wheels-bot:triage:2717 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->
wheels-bot commentedon May 15, 2026
Wheels Bot — Fix proposed
Draft PR: #2726
Spec:
vendor/wheels/tests/specs/view/paginationHelpersSpec.cfc— failing → passingImplementation:
vendor/wheels/view/pagination.cfcA human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides,
.ai/wheels/,CLAUDE.md) are handled separately bybot-update-docs.yml.fix(view): paginationNav rejects unknown sub-helper arguments (wheels…