fix(view): paginationNav anchor modes default to window-aware auto-suppress

CHANGELOG.md

@@ -32,6 +32,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Fixed
 
+- `paginationNav()` `showFirst` / `showLast` / `showPrevious` / `showNext` args now accept the tri-state strings `"auto"` / `"always"` / `"never"` (with backwards-compatible boolean coercion: `true` → `"always"`, `false` → `"never"`) and default to `"auto"`. Under `"auto"` the first/last anchors only render when the visible page-number window does not already reach the boundary — restoring the legacy 3.x `paginationLinks(alwaysShowAnchors=false)` semantics that a like-for-like swap to `paginationNav()` previously lost. Under `"auto"` the previous/next anchors always delegate to `previousPageLink()` / `nextPageLink()`, which render a disabled `<span class="disabled">` at the boundary by default — preserving the legacy `showPrevious=true` / `showNext=true` boundary indicator unless callers opt out with `"never"`. Adds a `windowSize` arg on `paginationNav()` so the auto-mode predicates stay coherent with `pageNumberLinks()`'s window (now passed explicitly to `pageNumberLinks()` instead of leaking through the anchor sub-helpers). Invalid strings throw `Wheels.InvalidArgument` at the call site
 - `wheels` `.deb` / `.rpm` Linux packages now ship the lucli-native `wheels-module` artifact, version + channel stamps, and a wrapper that routes through the bundled module — fixing the three v4.0.0 rpm regressions that broke `wheels start` on Rocky Linux during the titan production cutover. (1) `build-linux-packages.sh` now untars `wheels-module-${WHEELS_VERSION}.tar.gz` into `/opt/wheels/module/` instead of unzipping the CommandBox-shaped `wheels-cli-${WHEELS_VERSION}.zip`. (2) The LuCLI binary is staged as `/opt/wheels/wheels` so `basename(argv[0])` is `wheels` when the wrapper execs it — mirroring the brew formula and making LuCLI's module dispatcher resolve `wheels start` against the bundled module. (3) `nfpm-wheels.yaml` and `nfpm-wheels-be.yaml` now declare `/opt/wheels/.version` and `/opt/wheels/.channel` under `contents:` so `wheels --version` no longer returns `unknown (stable)`. (4) `tar` is declared as an rpm + deb runtime dependency since Rocky Linux 10 minimal cloud images do not ship it and any role that unpacks a tarball payload fails silently without it (#2700)
 - `wheels.middleware.RateLimiter` now validates `windowSeconds > 0` and `maxRequests >= 0` at construction. Previously, `windowSeconds = 0` leaked a generic CFML `You cannot divide by zero` exception out of the `fixedWindow` and `tokenBucket` strategies (and let every request through on `slidingWindow`), with no pointer back to the misconfigured `set(middleware = [...])` line. The constructor now throws `Wheels.RateLimiter.InvalidConfiguration` with a message naming the bad parameter — matching the pattern already used for `strategy`, `storage`, and `proxyStrategy`. `maxRequests = 0` remains legal (kill-switch idiom for "block every request") (#2693)
 - `wheels deploy --version=v1.2.3` (the form documented in the Kamal migration guide) no longer fails with `Invalid value for option '--version': 'v1.2.3' is not a boolean`. picocli treats `--version` as a `versionHelp = true` root flag and absorbs it during arg parsing before `Module.cfc` ever sees the subcommand, so the literal Kamal form was unreachable. The deploy parser now accepts `--release` as a picocli-safe alias (extracted into `cli/lucli/services/deploy/cli/DeployArgsParser.cfc` for unit-testability), and the brew/scoop wrappers rewrite `--version[=val]` → `--release[=val]` when `deploy` is the first positional — so the documented `--version` form keeps working on a current-channel wrapper, and users on an older wrapper can pass `--release` directly (#2674)

CLAUDE.md

@@ -462,7 +462,8 @@ Requires a paginated query: `findAll(page=params.page, perPage=25)`. The recomme
 ```cfm
 // All-in-one nav (wraps first/prev/page-numbers/next/last in <nav>)
 #paginationNav()#
-#paginationNav(showInfo=true, showFirst=false, showLast=false, navClass="my-pagination")#
+#paginationNav(showInfo=true, showFirst="never", showLast="never", navClass="my-pagination")#
+#paginationNav(windowSize=3)#  // widens window used by auto-mode boundary detection
 
 // Individual helpers for custom layouts
 #paginationInfo()#            // "Showing 26-50 of 1,000 records"
@@ -474,7 +475,7 @@ Requires a paginated query: `findAll(page=params.page, perPage=25)`. The recomme
 #pageNumberLinks(windowSize=5, classForCurrent="active")#
 ```
 
-Disabled links render as `<span class="disabled">` by default. All helpers accept `handle` for named pagination queries.
+`showFirst` / `showLast` / `showPrevious` / `showNext` accept `"auto"` (default), `"always"`, or `"never"`. Under `"auto"` the first/last anchors are hidden when the visible page-number window already reaches the boundary. Under `"auto"` the previous/next anchors always delegate to `previousPageLink()` / `nextPageLink()` — those render a disabled `<span class="disabled">` at the boundary so the position indicator is preserved; use `"never"` to hide the boundary indicator entirely. Booleans coerce for backwards compatibility (`true` → `"always"`, `false` → `"never"`). Disabled links render as `<span class="disabled">` by default. All helpers accept `handle` for named pagination queries.
 
 ## Testing Quick Reference
 

vendor/wheels/events/init/functions.cfm

@@ -311,12 +311,13 @@
 		};
 		application.$wheels.functions.paginationNav = {
 			navClass = "pagination",
-			showFirst = true,
-			showLast = true,
-			showPrevious = true,
-			showNext = true,
+			showFirst = "auto",
+			showLast = "auto",
+			showPrevious = "auto",
+			showNext = "auto",
 			showInfo = false,
 			showSinglePage = false,
+			windowSize = 2,
 			encode = true
 		};
 		application.$wheels.functions.paginationLinks = {

vendor/wheels/tests/specs/view/paginationHelpersSpec.cfc

@@ -237,8 +237,8 @@ component extends="wheels.WheelsTest" {
 					expect(result).toInclude("pagination")
 				})
 
-				it("includes all sections by default", () => {
-					g.model("author").findAll(page = 2, perPage = 3, order = "lastName")
+				it("includes all sections by default when window does not reach boundaries", () => {
+					g.setPagination(totalRecords = 100, currentPage = 5, perPage = 10)
 					result = _controller.paginationNav()
 					expect(result).toInclude("First")
 					expect(result).toInclude("Previous")
@@ -282,6 +282,115 @@ component extends="wheels.WheelsTest" {
 
 			})
 
+			/* ── paginationNav anchor display modes ────── */
+
+			describe("paginationNav anchor display modes", () => {
+
+				it("hides First in auto mode when window already reaches first page", () => {
+					g.setPagination(totalRecords = 12, currentPage = 2, perPage = 3)
+					result = _controller.paginationNav()
+					expect(result).notToInclude("First")
+				})
+
+				it("hides Last in auto mode when window already reaches last page", () => {
+					g.setPagination(totalRecords = 12, currentPage = 3, perPage = 3)
+					result = _controller.paginationNav()
+					expect(result).notToInclude("Last")
+				})
+
+				it("shows First in auto mode when window does not reach first page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 10, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("First")
+				})
+
+				it("shows Last in auto mode when window does not reach last page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 1, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("Last")
+				})
+
+				it("renders First with always mode when window already reaches first page", () => {
+					g.setPagination(totalRecords = 12, currentPage = 2, perPage = 3)
+					result = _controller.paginationNav(showFirst = "always")
+					expect(result).toInclude("First")
+				})
+
+				it("hides First with never mode when window does not reach first page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 10, perPage = 10)
+					result = _controller.paginationNav(showFirst = "never")
+					expect(result).notToInclude("First")
+				})
+
+				it("treats boolean true as always for backwards compatibility", () => {
+					g.setPagination(totalRecords = 12, currentPage = 2, perPage = 3)
+					result = _controller.paginationNav(showFirst = true, showLast = true)
+					expect(result).toInclude("First")
+					expect(result).toInclude("Last")
+				})
+
+				it("treats boolean false as never for backwards compatibility", () => {
+					g.setPagination(totalRecords = 100, currentPage = 5, perPage = 10)
+					result = _controller.paginationNav(showFirst = false, showLast = false)
+					expect(result).notToInclude("First")
+					expect(result).notToInclude("Last")
+				})
+
+				it("respects windowSize when computing auto mode predicates", () => {
+					g.setPagination(totalRecords = 100, currentPage = 5, perPage = 10)
+					result = _controller.paginationNav(windowSize = 4)
+					expect(result).notToInclude("First")
+				})
+
+				it("renders disabled Previous span in auto mode on first page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 1, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("Previous")
+					expect(result).toInclude("disabled")
+				})
+
+				it("renders Previous link in auto mode when not on first page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 3, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("Previous")
+					expect(result).toInclude("<a")
+				})
+
+				it("renders disabled Next span in auto mode on last page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 10, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("Next")
+					expect(result).toInclude("disabled")
+				})
+
+				it("renders Next link in auto mode when not on last page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 3, perPage = 10)
+					result = _controller.paginationNav()
+					expect(result).toInclude("Next")
+					expect(result).toInclude("<a")
+				})
+
+				it("hides Previous entirely with never mode on first page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 1, perPage = 10)
+					result = _controller.paginationNav(showPrevious = "never")
+					expect(result).notToInclude("Previous")
+				})
+
+				it("hides Next entirely with never mode on last page", () => {
+					g.setPagination(totalRecords = 100, currentPage = 10, perPage = 10)
+					result = _controller.paginationNav(showNext = "never")
+					expect(result).notToInclude("Next")
+				})
+
+				it("rejects unknown anchor mode strings", () => {
+					g.setPagination(totalRecords = 100, currentPage = 5, perPage = 10)
+					expect(() => {
+						_controller.paginationNav(showFirst = "bogus")
+					}).toThrow()
+				})
+
+			})
+
 		})
 
 	}

vendor/wheels/view/pagination.cfc

@@ -311,28 +311,39 @@ component {
 	 * Creates a complete pagination navigation element wrapping individual pagination helpers.
 	 * Outputs a `<nav>` element containing first/previous/page-numbers/next/last links and optional info text.
 	 *
+	 * The `showFirst` / `showLast` / `showPrevious` / `showNext` args accept the
+	 * strings `"auto"`, `"always"`, or `"never"`. Booleans are normalized for
+	 * backwards compatibility: `true` maps to `"always"`, `false` maps to `"never"`.
+	 * Under `"auto"` the first/last anchors only render when the visible page-number
+	 * window does not already reach the boundary (matching legacy 3.x semantics).
+	 * Under `"auto"` the previous/next anchors always delegate to their sub-helper,
+	 * which renders a disabled `<span class="disabled">` at the boundary by default —
+	 * use `"never"` to suppress the boundary indicator entirely.
+	 *
 	 * [section: View Helpers]
 	 * [category: Pagination Functions]
 	 *
 	 * @handle The handle given to the query that the pagination should be displayed for.
 	 * @navClass CSS class for the wrapping nav element.
-	 * @showFirst Whether to show the first page link.
-	 * @showLast Whether to show the last page link.
-	 * @showPrevious Whether to show the previous page link.
-	 * @showNext Whether to show the next page link.
+	 * @showFirst Anchor display mode for the first page link: "auto" (default), "always", "never", or boolean.
+	 * @showLast Anchor display mode for the last page link: "auto" (default), "always", "never", or boolean.
+	 * @showPrevious Anchor display mode for the previous page link: "auto" (default), "always", "never", or boolean.
+	 * @showNext Anchor display mode for the next page link: "auto" (default), "always", "never", or boolean.
 	 * @showInfo Whether to show the pagination info text.
 	 * @showSinglePage Whether to show pagination when there is only one page.
+	 * @windowSize Number of page links shown around the current page in `pageNumberLinks` and used by the auto-mode predicates.
 	 * @encode [see:styleSheetLinkTag].
 	 */
 	public string function paginationNav(
 		string handle = "query",
 		string navClass,
-		boolean showFirst,
-		boolean showLast,
-		boolean showPrevious,
-		boolean showNext,
+		any showFirst,
+		any showLast,
+		any showPrevious,
+		any showNext,
 		boolean showInfo,
 		boolean showSinglePage,
+		numeric windowSize,
 		any encode
 	) {
 		$args(name = "paginationNav", args = arguments);
@@ -347,39 +358,46 @@ component {
 		local.subArgs = {};
 		local.subArgs.handle = arguments.handle;
 		local.subArgs.encode = arguments.encode;
-		// Pass through any extra arguments (route, controller, action, key, params, etc.)
-		local.skipArgs = "handle,navClass,showFirst,showLast,showPrevious,showNext,showInfo,showSinglePage,encode";
+		// Pass through any extra arguments (route, controller, action, key, params, etc.).
+		// `windowSize` is excluded because the anchor sub-helpers do not declare it; it
+		// is delivered explicitly to `pageNumberLinks()` below.
+		local.skipArgs = "handle,navClass,showFirst,showLast,showPrevious,showNext,showInfo,showSinglePage,windowSize,encode";
 		for (local.key in arguments) {
 			if (!ListFindNoCase(local.skipArgs, local.key)) {
 				local.subArgs[local.key] = arguments[local.key];
 			}
 		}
 
+		local.firstMode = $paginationAnchorMode(value = arguments.showFirst, argName = "showFirst");
+		local.lastMode = $paginationAnchorMode(value = arguments.showLast, argName = "showLast");
+		local.previousMode = $paginationAnchorMode(value = arguments.showPrevious, argName = "showPrevious");
+		local.nextMode = $paginationAnchorMode(value = arguments.showNext, argName = "showNext");
+
 		local.content = "";
 
 		if (arguments.showInfo) {
 			local.content &= paginationInfo(argumentCollection = local.subArgs);
 			local.content &= " ";
 		}
 
-		if (arguments.showFirst) {
+		if ($paginationShouldShowAnchor(mode = local.firstMode, side = "first", pg = local.pg, windowSize = arguments.windowSize)) {
 			local.content &= firstPageLink(argumentCollection = local.subArgs);
 			local.content &= " ";
 		}
 
-		if (arguments.showPrevious) {
+		if ($paginationShouldShowAnchor(mode = local.previousMode, side = "previous", pg = local.pg, windowSize = arguments.windowSize)) {
 			local.content &= previousPageLink(argumentCollection = local.subArgs);
 			local.content &= " ";
 		}
 
-		local.content &= pageNumberLinks(argumentCollection = local.subArgs);
+		local.content &= pageNumberLinks(argumentCollection = local.subArgs, windowSize = arguments.windowSize);
 
-		if (arguments.showNext) {
+		if ($paginationShouldShowAnchor(mode = local.nextMode, side = "next", pg = local.pg, windowSize = arguments.windowSize)) {
 			local.content &= " ";
 			local.content &= nextPageLink(argumentCollection = local.subArgs);
 		}
 
-		if (arguments.showLast) {
+		if ($paginationShouldShowAnchor(mode = local.lastMode, side = "last", pg = local.pg, windowSize = arguments.windowSize)) {
 			local.content &= " ";
 			local.content &= lastPageLink(argumentCollection = local.subArgs);
 		}
@@ -392,6 +410,57 @@ component {
 		);
 	}
 
+	/**
+	 * Internal: normalizes a showFirst/showLast/showPrevious/showNext value into "auto" | "always" | "never".
+	 * Booleans are coerced: true -> "always", false -> "never". Strings are matched case-insensitively.
+	 * Public access required so $integrateComponents() pulls it into the view mixin scope on Lucee/Adobe.
+	 */
+	public string function $paginationAnchorMode(required any value, string argName = "anchor mode") {
+		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 = "Invalid pagination anchor mode '#arguments.value#' for argument '#arguments.argName#'.",
+			detail = "The argument must be one of 'auto', 'always', 'never', or a boolean."
+		);
+	}
+
+	/**
+	 * Internal: decides whether a first/previous/next/last anchor should render
+	 * given a normalized mode and the current pagination state.
+	 *
+	 * Under "auto" the first/last anchors only render when the visible page-number
+	 * window does not already reach the boundary. Previous/next under "auto" always
+	 * delegate to their sub-helper (`previousPageLink()` / `nextPageLink()`), which
+	 * renders a disabled `<span class="disabled">` at the boundary by default —
+	 * matching the legacy `showPrevious=true` / `showNext=true` behavior so the
+	 * boundary indicator is preserved unless the caller opts out with `"never"`.
+	 */
+	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;
+		}
+		switch (arguments.side) {
+			case "first":
+				return (arguments.pg.currentPage - arguments.windowSize) > 1;
+			case "last":
+				return arguments.pg.totalPages > (arguments.pg.currentPage + arguments.windowSize);
+		}
+		return true;
+	}
+
 	/**
 	 * Internal: renders a disabled span element for pagination.
 	 */

web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx

@@ -321,7 +321,7 @@ See [Packages](/v4-0-1-snapshot/digging-deeper/packages/) for manifest fields, p
 
 ### Monolithic `paginationLinks()`
 
-**CHANGELOG:** composable pagination helpers added (#1930). The 3.x `paginationLinks()` is retained. New code should use `paginationNav()` or compose the individual helpers (`paginationInfo`, `firstPageLink`, `previousPageLink`, `pageNumberLinks`, `nextPageLink`, `lastPageLink`).
+**CHANGELOG:** composable pagination helpers added (#1930). The 3.x `paginationLinks()` is retained. New code should use `paginationNav()` or compose the individual helpers (`paginationInfo`, `firstPageLink`, `previousPageLink`, `pageNumberLinks`, `nextPageLink`, `lastPageLink`). The 3.x `alwaysShowAnchors=false` behavior — hiding first/last when the page-number window already reaches the boundary — is now the default in `paginationNav()` via `showFirst="auto"` / `showLast="auto"` (default since v4.0.1, #2716). Pass `showFirst="always"` / `showLast="always"` to force the old always-visible behavior. The previous/next anchors under the new `showPrevious="auto"` / `showNext="auto"` defaults continue to delegate to `previousPageLink()` / `nextPageLink()`, which render a disabled `<span class="disabled">` at the boundary — matching the legacy `showPrevious=true` / `showNext=true` indicator. Use `showPrevious="never"` / `showNext="never"` to hide the boundary indicator entirely.
 
 ### RocketUnit test style