paginationNav() silently discards unknown arguments

[bpamiri]

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

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

view — see .ai/wheels/views/ for canonical patterns. The pagination helpers live in vendor/wheels/view/pagination.cfc.

Fix sketch

The fan-out lives at vendor/wheels/view/pagination.cfc:347-356 — paginationNav() builds local.subArgs by skipping its own named args and copying the rest into a struct that's passed via argumentCollection to 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 in subArgs that 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 $args registry the helpers themselves use), diff against the passed-through keys, and emit a one-time warning for the leftover set. Wheels has no central DeprecationLogger class (the report's snippet is illustrative); the existing pattern is an ad-hoc log() call or pushing onto a warnings array — see vendor/wheels/Plugins.cfc:556-564 for the closest precedent. Behavior choice (warn always vs warn-in-dev/throw-in-dev) is the main design call.

Confidence: medium

Layer 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]

Wheels Bot — Fix proposed

Draft PR: #2726

Spec: vendor/wheels/tests/specs/view/paginationHelpersSpec.cfc — failing → passing
Implementation: vendor/wheels/view/pagination.cfc

A 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 by bot-update-docs.yml.