From 36e10b47945adb52da9b8f60966a64af5bce0352 Mon Sep 17 00:00:00 2001
From: Mark Dumay <61946753+markdumay@users.noreply.github.com>
Date: Thu, 30 Jul 2026 16:00:24 +0200
Subject: [PATCH] fix(list): warn when pagination is not a selectable page size
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pagination` was passed straight through to the datatable without being
checked against the per-page options the control will offer. When the two
disagree the control renders its own first option while the table pages
at the requested size, so the reader sees "5" above a 25-row page. Nothing
surfaces at build time — it is visible only in a browser.

Warn instead, naming the value, the permitted set, the consequence and
both remedies. Skipped when the author supplies their own option list via
`pagination-select`, since the permitted set is then theirs.

Verified against a real site (infusal.io) with `pagination: 25`:

  WARN  partial [component-library/components/list/list.hugo.html] -
        Invalid pagination: integrations/_index.md
        pagination is 25, which is not one of 5, 10, 20, 50; the per-page
        control will show its first option instead. Pick a permitted
        value or set 'pagination-select'.

No warning at `pagination: 10`, and no warning when `paginate` is unset.
`pnpm test` (exampleSite build) passes: 40 pages, no errors.
---
 .../components/list/list.hugo.html            | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/component-library/components/list/list.hugo.html b/component-library/components/list/list.hugo.html
index 0ed529d..40e7286 100644
--- a/component-library/components/list/list.hugo.html
+++ b/component-library/components/list/list.hugo.html
@@ -107,6 +107,26 @@
 			{{ end }}
 
 			{{ $pagination := .pagination | default 10 }}
+
+			{{/* Warn when `pagination` is not one of the per-page options the
+			     datatable will offer. The control renders its own first option
+			     while the table pages at the requested size, so the two silently
+			     disagree — visible only in a browser. Skipped when the author
+			     supplies their own option list via `pagination-select`. */}}
+			{{ $paginationSelect := or .pagination_select (index . "pagination-select") }}
+			{{ if and .paginate (not $paginationSelect) }}
+				{{ $permitted := slice 5 10 20 50 }}
+				{{ if not (in $permitted $pagination) }}
+					{{ partial "utilities/LogWarn.html" (dict
+						"partial" "component-library/components/list/list.hugo.html"
+						"warnid"  "warn-invalid-pagination"
+						"msg"     "Invalid pagination"
+						"details" (printf "pagination is %v, which is not one of %v; the per-page control will show its first option instead. Pick a permitted value or set 'pagination-select'." $pagination (delimit $permitted ", "))
+						"file"    $page.File
+					)}}
+				{{ end }}
+			{{ end }}
+
 			{{ $paginate := and .paginate (gt (len $pages) $pagination) }}
 			{{ $sortable := and .sortable (gt (len $pages) 1) }}
 			{{ $searchable := and .searchable (gt (len $pages) 1) }}