paginationNav() default anchor-display UX differs from paginationLinks(alwaysShowAnchors=false)

[bpamiri]

Severity: medium — cosmetic regression on every paginated page after a like-for-like swap.

Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.

Description

paginationNav() exposes showFirst / showLast / showPrevious / showNext as booleans — they're either on or off for every page. The default is on.

paginationLinks(alwaysShowAnchors=false) (3.x default behavior) only emits the first / last anchors when the visible page-number window doesn't reach the boundary. So on page 4 of 4, it doesn't render "Last »" because the window already includes the last page.

This is the standard Bootstrap pagination UX. A 3.x app that swaps to paginationNav() will start showing "Last »" / "First «" on every page, including pages where they're redundant.

The arg surface to express "only show first/last when the window doesn't reach the ends" doesn't exist on paginationNav.

Suggested fix

Add an enum-style arg to paginationNav() and to the four primitive *PageLink helpers:

anchorDisplayMode = \"windowMisses\" | \"always\" | \"never\"

or equivalently:

showFirstWhen = \"windowMisses\" | \"always\" | \"never\"
showLastWhen  = \"windowMisses\" | \"always\" | \"never\"

Default to windowMisses to match legacy 3.x behavior.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:2716 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

paginationNav() (Wheels 4.0) exposes showFirst / showLast / showPrevious / showNext as plain booleans, default true. So "First «" / "Last »" anchors render on every page, including pages where the visible page-number window already reaches the boundary. The legacy 3.x paginationLinks(alwaysShowAnchors=true) guarded those anchors with (currentPage - windowSize) > 1 and totalPages > (currentPage + windowSize), so on page 4 of 4 "Last" was correctly suppressed. The requester proposes a tri-state enum ("windowMisses" | "always" | "never") defaulting to "windowMisses" to restore the 3.x semantics.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails (Kaminari)	first:/last: (String or nil), window:, outer_window:	Label-nilling: first: nil hides, present label always shows	No window-aware auto-suppression	out_of_range? returns empty; suppression only at exact boundary page
Laravel	onEachSide(int), no boolean toggle	Pure window-aware: UrlWindow::get() returns {first, slider, last} with null for sections that overlap the window	Only one mode; not configurable	4 internal layout modes auto-selected (small / too-close-to-start / too-close-to-end / full)
Django	show_first_last="true"/"false" (community), get_elided_page_range(on_ends=2) (core 3.2+)	Binary on/off in community helpers; core bakes boundaries into the windowed iterator	No window-vs-anchor coupling anywhere	has_other_pages() guards single-page case; redundant anchors not de-duped
Phoenix (Scrivener)	first: true, last: true, distance: 5	Boolean = permission, auto-suppressed when distance window covers boundary (guards page-distance>1 / page+distance<total)	Boolean only opts out; no force-always-show mode	hide_single: true suppresses single-page nav
Symfony (Knp + Pagerfanta)	pageRange / proximity (int); no boolean toggle	Window-aware computed; template emits first/last anchors iff startPage>1 / endPage<pageCount	Single integer knob; apps wanting always-show override the template	Window clamped to [1, nbPages] for small totals
Spring Boot (Thymeleaf, +1)	page.hasNext() / hasPrevious() / isFirst() / isLast()	No first-party helper, only primitives	Community split between hide-on-boundary and always-render-disabled; window-vs-anchor unrepresented	Spring stops at Page; template author rolls own

Justification for +1 = Spring Boot: confirms that even API-first frameworks stop at hasNext/hasPrevious primitives. Symfony is retained above; together they establish that no PHP/Java framework exposes a tri-state.

Dominant pattern

Four of six frameworks (Laravel, Phoenix Scrivener, Symfony Knp, Symfony Pagerfanta) converge on window-aware automatic suppression — first/last anchors render only when the visible page-number window does not already reach the boundary. The interface varies (Laravel/Symfony: no flag, computed; Phoenix: a boolean that means "permission, auto-suppressed"), but the semantics are identical and match Wheels 3.x paginationLinks(alwaysShowAnchors=true). Rails Kaminari and Django are outliers offering only binary always/never. Nobody ships a true tri-state enum — modern consensus is window-aware as the only sensible on state.

Recommended path for Wheels

Keep the four existing arg names on paginationNav() but widen them from boolean to string accepting "auto" | "always" | "never", default "auto". CFML's loose typing means existing 4.0 callers passing true/false keep working: true → "always", false → "never". New callers can pass "auto" (or omit the arg) for window-aware 3.x semantics. Smallest viable API change that matches modern consensus, restores 3.x default, and avoids a parallel arg surface (showFirstWhen etc) duplicating the existing one. Phoenix Scrivener is the closest precedent — same boolean-name retention, same "permission with window-aware auto-suppress" semantics — plus an explicit "always" for callers who do want a redundant boundary anchor.

// vendor/wheels/view/pagination.cfc
public string function paginationNav(
    string handle = "query",
    string navClass,
    string showFirst,        // "auto" (default) | "always" | "never" — also accepts true/false
    string showLast,
    string showPrevious,
    string showNext,
    boolean showInfo,
    boolean showSinglePage,
    any encode
) {
    // ...existing dollarArgs / pagination(handle) lookup...
    local.firstMode = $paginationAnchorMode(arguments.showFirst);
    if ($paginationShouldShowAnchor(mode=local.firstMode, side="first", pg=local.pg, windowSize=local.windowSize)) {
        local.content &= firstPageLink(argumentCollection = local.subArgs);
    }
    // symmetric for previous / next / last
}

// Public per CLAUDE.md "private mixin functions not integrated" cross-engine constraint
public string function $paginationAnchorMode(required any value) {
    if (IsBoolean(arguments.value)) return arguments.value ? "always" : "never";
    if (ListFindNoCase("auto,always,never", arguments.value)) return LCase(arguments.value);
    Throw(type="Wheels.InvalidArgument",
          message="paginationNav anchor mode must be 'auto', 'always', 'never', or a boolean.");
}

public boolean function $paginationShouldShowAnchor(
    required string mode, required string side,
    required struct pg, required numeric windowSize
) {
    if (arguments.mode == "never")  return false;
    if (arguments.mode == "always") return true;
    // "auto" — window-aware, matching 3.x paginationLinks(alwaysShowAnchors=true)
    switch (arguments.side) {
        case "first":    return (arguments.pg.currentPage - arguments.windowSize) > 1;
        case "previous": return arguments.pg.currentPage > 1;
        case "next":     return arguments.pg.currentPage < arguments.pg.totalPages;
        case "last":     return arguments.pg.totalPages > (arguments.pg.currentPage + arguments.windowSize);
    }
    return true;
}

Lives in: vendor/wheels/view/pagination.cfc. Defaults updated in vendor/wheels/events/init/functions.cfm to change showFirst = true → showFirst = "auto" (and the three siblings). The pageNumberLinks() helper already accepts windowSize (default 2); reuse that value when computing the auto-mode predicates so paginationNav and pageNumberLinks stay coherent.

Composes with: existing windowSize on pageNumberLinks(), existing showSinglePage boolean (unaffected), existing pagination handle / encode plumbing. No new infrastructure required.

Cross-engine notes

Clean. Uses IsBoolean(), ListFindNoCase(), LCase(), Throw(), and a switch on strings — all supported on Lucee 6/7, Adobe 2023/2025, BoxLang. No struct member functions, no bracket-notation method calls, no closures, no client/application/session reserved-scope traps. The $-prefixed helpers are public not private per the $integrateComponents() constraint in CLAUDE.md.

Open questions

• Should paginationNav accept its own windowSize arg, or always inherit from pageNumberLinks() defaults? (Leaning inherit.)
• Should the deprecated paginationLinks(alwaysShowAnchors=...) helper also gain the tri-state for symmetry, or is touching the legacy helper out-of-scope?
• The requester's sketch proposed "windowMisses" | "always" | "never"; this uses "auto" | "always" | "never" since auto is the idiomatic CFML/web-helper name for "framework decides". Happy to switch to "windowMisses" for semantic transparency.

Confidence: high

Dominant pattern is clear (window-aware = consensus across 4/6 frameworks), CFML sketch respects all Wheels conventions (named args, $-prefixed public helpers, no cross-engine APIs), +1 framework agrees in spirit, no new infrastructure, back-compat via type-widening is a one-line normalization.

Sources

• Rails / Kaminari: https://github.com/kaminari/kaminari/blob/master/kaminari-core/app/views/kaminari/_paginator.html.erb
• Rails / will_paginate: https://github.com/mislav/will_paginate/wiki/API-documentation
• Rails / Pagy: https://ddnexus.github.io/pagy/
• Laravel: https://github.com/laravel/framework/blob/master/src/Illuminate/Pagination/UrlWindow.php
• Laravel docs: https://laravel.com/docs/12.x/pagination
• Django: https://docs.djangoproject.com/en/5.1/topics/pagination/
• Phoenix / Scrivener: https://hexdocs.pm/scrivener_html/Scrivener.HTML.html
• Phoenix / flop_phoenix: https://hexdocs.pm/flop_phoenix/Flop.Phoenix.html
• Symfony / Knp: https://github.com/KnpLabs/KnpPaginatorBundle/blob/master/templates/Pagination/sliding.html.twig
• Symfony / Pagerfanta: https://github.com/BabDev/Pagerfanta/blob/3.x/lib/Core/View/TemplateView.php
• Spring Boot / Page: https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Page.html
• Spring Thymeleaf idioms: https://www.baeldung.com/spring-thymeleaf-pagination

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2733

Spec: vendor/wheels/tests/specs/view/paginationHelpersSpec.cfc — failing → passing
Implementation: vendor/wheels/view/pagination.cfc, vendor/wheels/events/init/functions.cfm

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.