From 195df444366a6702059e022f8b806fd478fb85d9 Mon Sep 17 00:00:00 2001
From: Ruslan <rvasylkiv@thingsboard.io>
Date: Fri, 12 Jun 2026 15:06:48 +0300
Subject: [PATCH 1/3] refactor(pagination): extract shared site-wide Pagination
 component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six surfaces each carried their own pagination: IoT Hub's link-based
PaginationLink + runtime updater, a button shell shared by Device
Library and Partners (with the windowing JS copy-pasted into both),
and bespoke innerHTML renderers on the blog and case-studies indexes.
Three drifted copies of the windowing algorithm, four styling
vocabularies, and recurring a11y gaps.

Replace all of it with src/components/Pagination/:

- Pagination.astro — one nav, two modes: basePath renders real
  anchors (SSG, rel=prev/next, crawlable); without it, buttons that
  dispatch bubbling tb-pagination:page-change events. Numbered list
  on desktop, compact 'Page X of Y' row below lg. Brand tokens
  (indigo/lavender current-page pill), aria-current in both modes,
  focus-visible rings.
- pagination-client.ts — updatePagination() rebuilds the lists for
  client-driven surfaces; restores keyboard focus to the equivalent
  control after each rebuild (fixes a focus-loss bug all the old
  implementations shared).
- pagination-shared.ts — the single windowing algorithm + strings.
- PerPageSelector.astro — the IoT-Hub-only items-per-page dropdown,
  composed in via the 'controls' slot from consumer files so its
  script/styles ship only to IoT Hub pages (Astro bundles per import
  graph, not per render).

Consumers keep what is theirs: URL state (?page= on blog), scroll
behavior, sessionStorage restore (case-studies), and the dynamic
search pipeline (IoT Hub) — the component only renders and reports.

Intended deltas: unified look on all surfaces, blog gains prev/next
chevrons, grid surfaces show full number rows up to 7 pages (was 5),
Device Library/Partners drop the redundant always-visible
'Page X of Y' line (lives in the sub-lg compact layout now).
---
 .../DeviceLibrary/DeviceLibrary.astro         | 119 +---
 src/components/DeviceLibrary/Pagination.astro | 160 -----
 src/components/IotHub/PaginationChevron.astro |  31 -
 src/components/IotHub/PaginationLink.astro    | 567 ------------------
 src/components/IotHub/SearchFilterBar.astro   |  12 +-
 .../IotHub/iot-hub-dynamic-search.ts          |  27 +-
 .../IotHub/iot-hub-pagination-update.ts       | 168 ------
 src/components/Pagination/Pagination.astro    | 366 +++++++++++
 .../Pagination/PerPageSelector.astro          | 294 +++++++++
 .../Pagination/pagination-client.ts           | 151 +++++
 .../Pagination/pagination-shared.ts           |  37 ++
 src/components/Partners/PartnerLibrary.astro  | 100 +--
 src/models/iot-hub.ts                         |   9 -
 src/pages/blog/index.astro                    |  94 +--
 src/pages/case-studies/index.astro            | 167 +-----
 src/pages/iot-hub/[category]/[...page].astro  |   9 +-
 16 files changed, 961 insertions(+), 1350 deletions(-)
 delete mode 100644 src/components/DeviceLibrary/Pagination.astro
 delete mode 100644 src/components/IotHub/PaginationChevron.astro
 delete mode 100644 src/components/IotHub/PaginationLink.astro
 delete mode 100644 src/components/IotHub/iot-hub-pagination-update.ts
 create mode 100644 src/components/Pagination/Pagination.astro
 create mode 100644 src/components/Pagination/PerPageSelector.astro
 create mode 100644 src/components/Pagination/pagination-client.ts
 create mode 100644 src/components/Pagination/pagination-shared.ts

diff --git a/src/components/DeviceLibrary/DeviceLibrary.astro b/src/components/DeviceLibrary/DeviceLibrary.astro
index b58cf7ac7b..c4c54f5619 100644
--- a/src/components/DeviceLibrary/DeviceLibrary.astro
+++ b/src/components/DeviceLibrary/DeviceLibrary.astro
@@ -3,7 +3,7 @@ import { Icon } from 'astro-icon/components';
 import DeviceCard from './DeviceCard.astro';
 import FilterSidebar from './FilterSidebar.astro';
 import SearchBar from './SearchBar.astro';
-import Pagination from './Pagination.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
 import { PLATFORM_VALUES } from '~/util/device-platform';
 
 interface Device {
@@ -39,10 +39,6 @@ const t = {
 	noResults: 'No devices match your filters.',
 	devicesFound: 'devices found',
 	searchPlaceholder: 'Search devices...',
-	previous: 'Previous',
-	next: 'Next',
-	page: 'Page',
-	of: 'of',
 };
 
 // Extract unique filter values with counts
@@ -158,7 +154,7 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 			{t.noResults}
 		</div>
 
-		<Pagination translations={{ previous: t.previous, next: t.next, page: t.page, of: t.of }} />
+		<Pagination hidden />
 	</div>
 </div>
 
@@ -174,6 +170,7 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 </script>
 
 <script>
+	import { updatePagination } from '@components/Pagination/pagination-client';
 	import {
 		platformToQueryParam,
 		queryParamToPlatform,
@@ -276,9 +273,9 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 		// DOM-level idempotency marker — `astro:page-load` fires on both the
 		// initial page load and on every view-transition navigation, so this
 		// handler can run multiple times against the same DOM. Without the
-		// marker every filter checkbox / pagination button / search input
-		// would accumulate listeners (pagination Prev/Next would skip two
-		// pages per click, search debounce would leak timers, etc.).
+		// marker every filter checkbox / pagination nav / search input
+		// would accumulate listeners (each page change would rerun
+		// updateDisplay per duplicate, search debounce would leak timers).
 		if (container.dataset.inited === 'true') return;
 		container.dataset.inited = 'true';
 
@@ -297,15 +294,9 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 		);
 		const searchInput = container.querySelector('#device-search') as HTMLInputElement;
 		const searchClearBtn = container.querySelector('#search-clear') as HTMLButtonElement;
-		const pagination = container.querySelector('#pagination') as HTMLElement;
-		const paginationPages = container.querySelector('#pagination-pages') as HTMLElement;
-		const paginationPrev = container.querySelector('#pagination-prev') as HTMLButtonElement;
-		const paginationNext = container.querySelector('#pagination-next') as HTMLButtonElement;
-		const paginationInfo = container.querySelector('#pagination-info') as HTMLElement;
-		const paginationCurrent = container.querySelector('#pagination-current') as HTMLElement;
-		const paginationTotal = container.querySelector('#pagination-total') as HTMLElement;
+		const paginationNav = container.querySelector('[data-tb-pagination]') as HTMLElement;
 
-		if (!deviceGrid || !deviceCountEl || !searchInput) return;
+		if (!deviceGrid || !deviceCountEl || !searchInput || !paginationNav) return;
 
 		const pageSize = parseInt(container.getAttribute('data-page-size') || '12', 10);
 		let currentPage = 1;
@@ -421,58 +412,6 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 			`;
 		}
 
-		function renderPagination(currentPage: number, totalPages: number) {
-			if (totalPages <= 1) {
-				pagination.hidden = true;
-				paginationInfo.hidden = true;
-				return;
-			}
-
-			pagination.hidden = false;
-			paginationInfo.hidden = false;
-
-			paginationPrev.disabled = currentPage <= 1;
-			paginationNext.disabled = currentPage >= totalPages;
-
-			paginationCurrent.textContent = String(currentPage);
-			paginationTotal.textContent = String(totalPages);
-
-			// Generate page buttons
-			const pages: (number | string)[] = [];
-			const maxVisible = 5;
-
-			if (totalPages <= maxVisible) {
-				for (let i = 1; i <= totalPages; i++) pages.push(i);
-			} else {
-				pages.push(1);
-
-				if (currentPage > 3) {
-					pages.push('...');
-				}
-
-				const start = Math.max(2, currentPage - 1);
-				const end = Math.min(totalPages - 1, currentPage + 1);
-
-				for (let i = start; i <= end; i++) {
-					if (!pages.includes(i)) pages.push(i);
-				}
-
-				if (currentPage < totalPages - 2) {
-					pages.push('...');
-				}
-
-				if (!pages.includes(totalPages)) pages.push(totalPages);
-			}
-
-			paginationPages.innerHTML = pages
-				.map((p) =>
-					typeof p === 'number'
-						? `<button type="button" class="page-btn${p === currentPage ? ' active' : ''}" data-page="${p}">${p}</button>`
-						: `<span class="page-ellipsis">${p}</span>`
-				)
-				.join('');
-		}
-
 		function updateDisplay() {
 			const result = api.search({
 				search: searchInput.value.trim(),
@@ -495,7 +434,11 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 
 			// Update pagination
 			currentPage = result.currentPage;
-			renderPagination(result.currentPage, result.totalPages);
+			updatePagination(paginationNav, {
+				currentPage: result.currentPage,
+				totalPages: result.totalPages,
+				hideOnSinglePage: true,
+			});
 
 			// Update search clear button
 			searchClearBtn.hidden = !searchInput.value;
@@ -545,32 +488,12 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 			searchInput.focus();
 		});
 
-		paginationPrev?.addEventListener('click', () => {
-			if (currentPage > 1) {
-				currentPage--;
-				updateDisplay();
-				deviceGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
-			}
-		});
-
-		paginationNext?.addEventListener('click', () => {
-			currentPage++;
+		paginationNav.addEventListener('tb-pagination:page-change', (e) => {
+			currentPage = (e as CustomEvent<{ page: number }>).detail.page;
 			updateDisplay();
 			deviceGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
 		});
 
-		paginationPages?.addEventListener('click', (e) => {
-			const target = e.target as HTMLElement;
-			if (target.classList.contains('page-btn')) {
-				const page = parseInt(target.dataset.page || '1', 10);
-				if (page !== currentPage) {
-					currentPage = page;
-					updateDisplay();
-					deviceGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
-				}
-			}
-		});
-
 		// Initial render is already done by Astro, just set up pagination.
 		// Skip when ?platform= was present — updateDisplay() above already rendered
 		// pagination for the filtered set; rendering for the unfiltered total
@@ -578,7 +501,11 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 		if (!hadUrlPlatform) {
 			const initialTotal = allDevices.length;
 			const initialTotalPages = Math.ceil(initialTotal / pageSize);
-			renderPagination(1, initialTotalPages);
+			updatePagination(paginationNav, {
+				currentPage: 1,
+				totalPages: initialTotalPages,
+				hideOnSinglePage: true,
+			});
 		}
 	}
 
@@ -683,6 +610,12 @@ const initialDevices = devicesWithHref.slice(0, PAGE_SIZE);
 		display: none;
 	}
 
+	// Grid → pagination gap the old shell carried; vanishes with the nav's
+	// own `display: none` when it hides on single-page results.
+	.device-library-main :global(.tb-pagination) {
+		margin-top: 2rem;
+	}
+
 	@media (max-width: 768px) {
 		.device-library {
 			flex-direction: column;
diff --git a/src/components/DeviceLibrary/Pagination.astro b/src/components/DeviceLibrary/Pagination.astro
deleted file mode 100644
index a5af927eec..0000000000
--- a/src/components/DeviceLibrary/Pagination.astro
+++ /dev/null
@@ -1,160 +0,0 @@
----
-interface Props {
-	translations: {
-		previous: string;
-		next: string;
-		page: string;
-		of: string;
-	};
-}
-
-const { translations } = Astro.props;
----
-
-<nav class="pagination" id="pagination" hidden aria-label="Pagination">
-	<button type="button" class="pagination-btn pagination-prev" id="pagination-prev" disabled>
-		<svg
-			xmlns="http://www.w3.org/2000/svg"
-			width="16"
-			height="16"
-			viewBox="0 0 24 24"
-			fill="none"
-			stroke="currentColor"
-			stroke-width="2"
-			stroke-linecap="round"
-			stroke-linejoin="round"
-		>
-			<path d="m15 18-6-6 6-6"></path>
-		</svg>
-		<span class="pagination-btn-text">{translations.previous}</span>
-	</button>
-
-	<div class="pagination-pages" id="pagination-pages">
-		<!-- Dynamically populated by JS -->
-	</div>
-
-	<button type="button" class="pagination-btn pagination-next" id="pagination-next" disabled>
-		<span class="pagination-btn-text">{translations.next}</span>
-		<svg
-			xmlns="http://www.w3.org/2000/svg"
-			width="16"
-			height="16"
-			viewBox="0 0 24 24"
-			fill="none"
-			stroke="currentColor"
-			stroke-width="2"
-			stroke-linecap="round"
-			stroke-linejoin="round"
-		>
-			<path d="m9 18 6-6-6-6"></path>
-		</svg>
-	</button>
-</nav>
-
-<div class="pagination-info" id="pagination-info" hidden>
-	<span>{translations.page}</span>
-	<span id="pagination-current">1</span>
-	<span>{translations.of}</span>
-	<span id="pagination-total">1</span>
-</div>
-
-<style>
-	.pagination {
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		gap: 0.5rem;
-		margin-top: 2rem;
-	}
-
-	.pagination[hidden] {
-		display: none;
-	}
-
-	.pagination-btn {
-		display: flex;
-		align-items: center;
-		gap: 0.375rem;
-		padding: 0rem 0.75rem;
-		font-size: 0.875rem;
-		border: 1px solid var(--sl-color-gray-5);
-		border-radius: 0.375rem;
-		background: var(--sl-color-bg-nav);
-		color: var(--sl-color-text);
-		cursor: pointer;
-		transition:
-			border-color 0.2s,
-			background 0.2s;
-	}
-
-	.pagination-btn:hover:not(:disabled) {
-		border-color: var(--sl-color-text-accent);
-		background: var(--sl-color-gray-6);
-	}
-
-	.pagination-btn:disabled {
-		opacity: 0.5;
-		cursor: not-allowed;
-	}
-
-	.pagination-pages {
-		display: flex;
-		align-items: center;
-		gap: 0.25rem;
-	}
-
-	.pagination-pages :global(.page-btn) {
-		min-width: 2rem;
-		height: 2rem;
-		padding: 0 0.5rem;
-		font-size: 0.875rem;
-		border: 1px solid var(--sl-color-gray-5);
-		border-radius: 0.375rem;
-		background: var(--sl-color-bg-nav);
-		color: var(--sl-color-text);
-		cursor: pointer;
-		transition:
-			border-color 0.2s,
-			background 0.2s;
-	}
-
-	.pagination-pages :global(.page-btn:hover) {
-		border-color: var(--sl-color-text-accent);
-		background: var(--sl-color-gray-6);
-	}
-
-	.pagination-pages :global(.page-btn.active) {
-		background: var(--sl-color-text-accent);
-		border-color: var(--sl-color-text-accent);
-		color: var(--sl-color-bg);
-	}
-
-	.pagination-pages :global(.page-ellipsis) {
-		padding: 0 0.25rem;
-		color: var(--sl-color-gray-3);
-	}
-
-	.pagination-info {
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		gap: 0.25rem;
-		margin-top: 0.75rem;
-		font-size: 0.875rem;
-		color: var(--sl-color-gray-2);
-	}
-
-	.pagination-info[hidden] {
-		display: none;
-	}
-
-	@media (max-width: 480px) {
-		.pagination-btn-text {
-			display: none;
-		}
-
-		.pagination-btn {
-			padding: 0.5rem;
-		}
-	}
-</style>
diff --git a/src/components/IotHub/PaginationChevron.astro b/src/components/IotHub/PaginationChevron.astro
deleted file mode 100644
index caf8dc3658..0000000000
--- a/src/components/IotHub/PaginationChevron.astro
+++ /dev/null
@@ -1,31 +0,0 @@
----
-import Chevron from '@components/Chevron.astro';
-
-interface Props {
-	direction: 'left' | 'right';
-	href?: string;
-	disabled?: boolean;
-	label: string;
-}
-
-const { direction, href, disabled = false, label } = Astro.props;
-const rel = direction === 'left' ? 'prev' : 'next';
-const isDisabled = disabled || !href;
----
-
-{
-	isDisabled ? (
-		<span class="iot-hub-pagination__chevron is-disabled" aria-hidden="true">
-			<Chevron direction={direction} size={24} />
-		</span>
-	) : (
-		<a
-			class="iot-hub-pagination__chevron"
-			href={href}
-			rel={rel}
-			aria-label={label}
-		>
-			<Chevron direction={direction} size={24} />
-		</a>
-	)
-}
diff --git a/src/components/IotHub/PaginationLink.astro b/src/components/IotHub/PaginationLink.astro
deleted file mode 100644
index 0fee98e2df..0000000000
--- a/src/components/IotHub/PaginationLink.astro
+++ /dev/null
@@ -1,567 +0,0 @@
----
-import { PAGE_SIZE, IOT_HUB_STRINGS, formatPageSummary } from '@models/iot-hub';
-import Chevron from '@components/Chevron.astro';
-import IotHubIcon from './IotHubIcon.astro';
-import PaginationChevron from './PaginationChevron.astro';
-
-interface Props {
-	currentPage: number;
-	totalPages: number;
-	basePath: string;
-	/** Items-per-page value shown in the (decorative) selector. */
-	perPage?: number;
-	/**
-	 * Layout variant:
-	 *   - 'centered' (default) — page-numbers centred, items-per-page
-	 *     absolutely pinned to the right edge.
-	 *   - 'right' — everything right-aligned in a single flex row, items-
-	 *     per-page sits inline after the page numbers.
-	 */
-	variant?: 'centered' | 'right';
-}
-
-const {
-	currentPage,
-	totalPages,
-	basePath,
-	perPage = PAGE_SIZE,
-	variant = 'centered',
-} = Astro.props;
-
-const pageUrl = (n: number): string => (n === 1 ? basePath : `${basePath}${n}/`);
-
-function buildPages(current: number, total: number): Array<number | 'ellipsis'> {
-	if (total <= 7) {
-		return Array.from({ length: total }, (_, i) => i + 1);
-	}
-	const result: Array<number | 'ellipsis'> = [1];
-	if (current > 3) result.push('ellipsis');
-	for (let p = Math.max(2, current - 1); p <= Math.min(total - 1, current + 1); p++) {
-		result.push(p);
-	}
-	if (current < total - 2) result.push('ellipsis');
-	result.push(total);
-	return result;
-}
-
-const items = buildPages(currentPage, totalPages);
-const prevHref = currentPage > 1 ? pageUrl(currentPage - 1) : undefined;
-const nextHref = currentPage < totalPages ? pageUrl(currentPage + 1) : undefined;
-
-// Items-per-page selector: three multiples of `perPage`. The dropdown
-// dispatches `iot-hub-page-size:change` { perPage } on selection so the
-// host (the future dynamic-search pipeline) can refetch.
-const perPageOptions = [perPage, perPage * 2, perPage * 3];
----
-
-<nav
-	class:list={['iot-hub-pagination', `iot-hub-pagination--${variant}`]}
-	aria-label="Pagination"
-	data-iot-hub-pagination
->
-	<div class="iot-hub-pagination__pages-wrap">
-		<ul class="iot-hub-pagination__pages iot-hub-pagination__pages--numbers">
-			<li>
-				<PaginationChevron
-					direction="left"
-					href={prevHref}
-					label={IOT_HUB_STRINGS.pagination.prevPageAriaLabel}
-				/>
-			</li>
-			{
-				items.map((item) =>
-					item === 'ellipsis' ? (
-						<li class="iot-hub-pagination__ellipsis" aria-hidden="true">
-							…
-						</li>
-					) : (
-						<li>
-							<a
-								class={`iot-hub-pagination__page${item === currentPage ? ' is-current' : ''}`}
-								href={pageUrl(item)}
-								aria-current={item === currentPage ? 'page' : undefined}
-							>
-								{item}
-							</a>
-						</li>
-					)
-				)
-			}
-			<li>
-				<PaginationChevron
-					direction="right"
-					href={nextHref}
-					label={IOT_HUB_STRINGS.pagination.nextPageAriaLabel}
-				/>
-			</li>
-		</ul>
-		<div class="iot-hub-pagination__pages iot-hub-pagination__pages--compact">
-			<PaginationChevron
-				direction="left"
-				href={prevHref}
-				label={IOT_HUB_STRINGS.pagination.prevPageAriaLabel}
-			/>
-			<span class="iot-hub-pagination__summary">
-				{formatPageSummary(currentPage, totalPages)}
-			</span>
-			<PaginationChevron
-				direction="right"
-				href={nextHref}
-				label={IOT_HUB_STRINGS.pagination.nextPageAriaLabel}
-			/>
-		</div>
-	</div>
-	<div
-		class="iot-hub-pagination__per-page"
-		data-per-page-root
-		data-per-page={perPage}
-	>
-		<span class="iot-hub-pagination__per-page-label" id="iot-hub-per-page-label">
-			Items per page:
-		</span>
-		<button
-			type="button"
-			class="iot-hub-pagination__per-page-value"
-			data-per-page-button
-			aria-expanded="false"
-			aria-labelledby="iot-hub-per-page-label"
-		>
-			<span data-per-page-label>{perPage}</span>
-			<Chevron direction="down" />
-		</button>
-		<div
-			class="iot-hub-pagination__per-page-popup"
-			hidden
-			data-per-page-popup
-			role="group"
-			aria-label="Items per page"
-		>
-			{perPageOptions.map((n) => (
-				<button
-					type="button"
-					class:list={[
-						'iot-hub-pagination__per-page-option',
-						n === perPage && 'iot-hub-pagination__per-page-option--selected',
-					]}
-					data-per-page-option
-					data-per-page-value={n}
-					aria-pressed={n === perPage}
-				>
-					<span class="iot-hub-pagination__per-page-option-text">{n}</span>
-					<IotHubIcon
-						icon="check"
-						size={24}
-						class="iot-hub-pagination__per-page-option-check"
-					/>
-				</button>
-			))}
-		</div>
-	</div>
-</nav>
-
-<style is:global lang="scss">
-	@use '../../styles/_variables.scss' as *;
-
-	.iot-hub-pagination {
-		position: relative;
-		// Establishes a stacking context (z-index !== auto) so the
-		// per-page popup floats above the page sections that follow the
-		// pagination in DOM order. Without this, the popup ends up below
-		// later sections — they aren't z-indexed either, but DOM order
-		// wins for elements at the same stacking level.
-		z-index: 5;
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		padding: 0 16px;
-		min-height: 40px;
-
-		@include media-down(sm) {
-			padding: 0 12px;
-		}
-	}
-
-	// `right` variant — single right-aligned row. Used by surfaces where
-	// the centred layout would leave a big empty column to the left
-	// (e.g. the search-page filter bar).
-	.iot-hub-pagination--right {
-		justify-content: flex-end;
-		gap: 16px;
-		padding-right: 0;
-
-		.iot-hub-pagination__pages-wrap {
-			flex: 0;
-		}
-
-		.iot-hub-pagination__per-page {
-			position: relative;
-			top: auto;
-			right: auto;
-			transform: none;
-		}
-	}
-
-	.iot-hub-pagination__pages-wrap {
-		display: flex;
-		justify-content: center;
-		flex: 1 1 0;
-	}
-
-	.iot-hub-pagination__pages {
-		display: flex;
-		align-items: center;
-		gap: 1px;
-		list-style: none;
-		margin: 0;
-		padding: 0;
-	}
-
-	.iot-hub-pagination__pages--compact {
-		display: none;
-		gap: 8px;
-	}
-
-	@include media-down(lg) {
-		.iot-hub-pagination__pages--numbers {
-			display: none;
-		}
-
-		.iot-hub-pagination__pages--compact {
-			display: flex;
-		}
-	}
-
-	// Mixin (not %placeholder + @extend) because @extend doesn't reliably
-	// reach across `:global()` selectors after Astro's SCSS pipeline rewrites
-	// them. Also: `font-family: inherit` / `appearance: none` / `cursor: pointer`
-	// are explicit so dynamic-mode <button> elements render visually identical
-	// to their static-mode <a> counterparts without UA defaults leaking in.
-	@mixin pagination-btn {
-		display: inline-flex;
-		align-items: center;
-		justify-content: center;
-		min-width: 40px;
-		height: 40px;
-		padding: 8px;
-		border: none;
-		border-radius: 8px;
-		font-family: inherit;
-		font-size: 14px;
-		font-weight: $font-weight-semibold;
-		line-height: 24px;
-		text-decoration: none;
-		color: var(--color-text-secondary);
-		background: transparent;
-		appearance: none;
-		cursor: pointer;
-		transition: background $transition-fast, color $transition-fast;
-
-		svg {
-			display: block;
-		}
-	}
-
-	.iot-hub-pagination__chevron {
-		@include pagination-btn;
-
-		&:hover,
-		&:focus-visible {
-			background: var(--color-bg-light);
-			color: var(--color-text);
-		}
-
-		&.is-disabled {
-			opacity: 0.4;
-			pointer-events: none;
-		}
-	}
-
-	.iot-hub-pagination__page {
-		@include pagination-btn;
-		padding: 8px 16px;
-		color: var(--color-text);
-
-		&:hover,
-		&:focus-visible {
-			background: var(--color-bg-light);
-		}
-
-		&.is-current {
-			background: var(--color-primary);
-			color: #fff;
-			pointer-events: none;
-		}
-
-		[data-theme='dark'] &.is-current {
-			background: #b3c7ff;
-			color: #17181c;
-		}
-	}
-
-	.iot-hub-pagination__ellipsis {
-		display: inline-flex;
-		align-items: center;
-		justify-content: center;
-		min-width: 40px;
-		height: 40px;
-		padding: 8px 16px;
-		font-size: 14px;
-		font-weight: $font-weight-semibold;
-		line-height: 24px;
-		color: var(--sl-color-gray-5);
-	}
-
-	.iot-hub-pagination__summary {
-		display: inline-flex;
-		align-items: center;
-		height: 40px;
-		font-size: 14px;
-		font-weight: $font-weight-semibold;
-		line-height: 24px;
-		color: var(--color-text);
-		white-space: nowrap;
-	}
-
-	.iot-hub-pagination__per-page {
-		position: absolute;
-		top: 50%;
-		right: 16px;
-		transform: translateY(-50%);
-		display: inline-flex;
-		align-items: center;
-		gap: 8px;
-		font-size: 14px;
-		line-height: 24px;
-		color: var(--color-text-muted);
-
-		@include media-down(lg) {
-			display: none;
-		}
-	}
-
-	.iot-hub-pagination__per-page-label {
-		white-space: nowrap;
-	}
-
-	.iot-hub-pagination__per-page-value {
-		display: inline-flex;
-		align-items: center;
-		gap: 8px;
-		min-height: 40px;
-		min-width: 72px;
-		padding: 8px 8px 8px 12px;
-		border: 1px solid var(--color-border);
-		border-radius: 8px;
-		color: var(--color-text);
-		font-family: inherit;
-		font-size: 14px;
-		line-height: 24px;
-		font-weight: $font-weight-normal;
-		cursor: pointer;
-		background: var(--color-bg-surface);
-		transition: background-color $transition-fast, border-color $transition-fast;
-
-		&:hover,
-		&[aria-expanded='true'] {
-			background: var(--sl-color-gray-6);
-		}
-
-		svg {
-			color: var(--color-text-secondary);
-		}
-
-		[data-theme='dark'] & {
-			border-color: #23262f;
-		}
-	}
-
-	// Popup anchored below the button. `right: 0` keeps it aligned to the
-	// trigger's right edge so longer option labels expand leftward into the
-	// row's empty space rather than overflowing the viewport.
-	.iot-hub-pagination__per-page-popup {
-		position: absolute;
-		top: calc(100% + 4px);
-		right: 0;
-		min-width: 100%;
-		display: flex;
-		flex-direction: column;
-		padding: 4px;
-		background: var(--color-bg-surface);
-		border: 1px solid var(--iot-hub-hairline, rgba(0, 0, 0, 0.12));
-		border-radius: 8px;
-		box-shadow:
-			0 1px 0.5px rgba(0, 0, 0, 0.12),
-			0 2px 0.5px rgba(0, 0, 0, 0.24);
-		// Within the .iot-hub-pagination stacking context (z-index: 5 on
-		// the nav), this is the local stacking level — high enough to
-		// clear any other internal absolutely-positioned siblings.
-		z-index: 100;
-
-		[data-theme='dark'] & {
-			border-color: #23262f;
-			background: #17181c;
-		}
-
-		// Enter animation parity with IotHubSort / hero autocomplete —
-		// 120ms decel curve. Pivot is top-right so the popup expands
-		// downward from the button corner.
-		transform-origin: top right;
-		animation: iot-hub-pagination-per-page-enter 120ms cubic-bezier(0, 0, 0.2, 1);
-
-		&[hidden] {
-			display: none;
-		}
-	}
-
-	@keyframes iot-hub-pagination-per-page-enter {
-		from {
-			transform: scaleY(0);
-			opacity: 0;
-		}
-		to {
-			transform: scaleY(1);
-			opacity: 1;
-		}
-	}
-
-	@media (prefers-reduced-motion: reduce) {
-		.iot-hub-pagination__per-page-popup {
-			animation: none;
-		}
-	}
-
-	.iot-hub-pagination__per-page-option {
-		display: flex;
-		align-items: center;
-		gap: 8px;
-		width: 100%;
-		padding: 8px 12px;
-		font-family: inherit;
-		font-size: 14px;
-		font-weight: $font-weight-semibold;
-		line-height: 24px;
-		color: var(--sl-color-gray-2);
-		background: transparent;
-		border: none;
-		border-radius: 5px;
-		cursor: pointer;
-		text-align: left;
-		transition: background-color $transition-fast;
-
-		&:hover {
-			background: var(--sl-color-gray-6);
-		}
-
-		&:focus-visible {
-			outline: 2px solid var(--color-primary);
-			outline-offset: -2px;
-		}
-	}
-
-	.iot-hub-pagination__per-page-option-text {
-		flex: 1 1 0;
-		min-width: 0;
-	}
-
-	.iot-hub-pagination__per-page-option-check {
-		flex-shrink: 0;
-		visibility: hidden;
-	}
-
-	.iot-hub-pagination__per-page-option--selected {
-		background: var(--sl-color-gray-6);
-		color: var(--color-primary);
-
-		[data-theme='dark'] & {
-			color: #b3c7ff;
-		}
-
-		.iot-hub-pagination__per-page-option-check {
-			visibility: visible;
-		}
-	}
-</style>
-
-<script>
-	// Items-per-page dropdown. Click toggles, option click commits +
-	// closes + dispatches `iot-hub-page-size:change` { perPage } on the
-	// root for the future dynamic-search pipeline to listen to.
-
-	function setupPerPage(root: HTMLElement) {
-		if (root.dataset.perPageInited) return;
-		root.dataset.perPageInited = 'true';
-
-		const button = root.querySelector<HTMLButtonElement>('[data-per-page-button]');
-		const popup = root.querySelector<HTMLElement>('[data-per-page-popup]');
-		const label = root.querySelector<HTMLElement>('[data-per-page-label]');
-		if (!button || !popup || !label) return;
-
-		const options = Array.from(
-			root.querySelectorAll<HTMLButtonElement>('[data-per-page-option]')
-		);
-
-		function openPopup() {
-			popup!.hidden = false;
-			button!.setAttribute('aria-expanded', 'true');
-		}
-
-		function closePopup() {
-			popup!.hidden = true;
-			button!.setAttribute('aria-expanded', 'false');
-		}
-
-		button.addEventListener('click', (e) => {
-			e.stopPropagation();
-			if (popup.hidden) openPopup();
-			else closePopup();
-		});
-
-		for (const opt of options) {
-			opt.addEventListener('click', (e) => {
-				e.stopPropagation();
-				const value = Number.parseInt(opt.dataset.perPageValue ?? '0', 10);
-				if (!Number.isFinite(value) || value <= 0) return;
-				for (const o of options) {
-					const isSelected = o === opt;
-					o.classList.toggle(
-						'iot-hub-pagination__per-page-option--selected',
-						isSelected
-					);
-					o.setAttribute('aria-pressed', String(isSelected));
-				}
-				label!.textContent = String(value);
-				root.dataset.perPage = String(value);
-				closePopup();
-				root.dispatchEvent(
-					new CustomEvent('iot-hub-page-size:change', {
-						detail: { perPage: value },
-						bubbles: true,
-					})
-				);
-			});
-		}
-
-		document.addEventListener('click', (e) => {
-			if (!popup.hidden && !root.contains(e.target as Node)) closePopup();
-		});
-		root.addEventListener('keydown', (e) => {
-			if (e.key === 'Escape' && !popup.hidden) {
-				closePopup();
-				button!.focus();
-			}
-		});
-	}
-
-	function initAll() {
-		document
-			.querySelectorAll<HTMLElement>('[data-per-page-root]')
-			.forEach(setupPerPage);
-	}
-
-	if (document.readyState === 'loading') {
-		document.addEventListener('DOMContentLoaded', initAll);
-	} else {
-		initAll();
-	}
-	document.addEventListener('astro:page-load', initAll);
-</script>
diff --git a/src/components/IotHub/SearchFilterBar.astro b/src/components/IotHub/SearchFilterBar.astro
index 41beb676f8..992ea1ec1f 100644
--- a/src/components/IotHub/SearchFilterBar.astro
+++ b/src/components/IotHub/SearchFilterBar.astro
@@ -1,7 +1,8 @@
 ---
 import { IOT_HUB_STRINGS, SEARCH_PAGE_SIZE } from '@models/iot-hub';
 import IotHubSort from './IotHubSort.astro';
-import PaginationLink from './PaginationLink.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
+import PerPageSelector from '@components/Pagination/PerPageSelector.astro';
 
 const T = IOT_HUB_STRINGS.searchPage;
 
@@ -88,13 +89,14 @@ const dynamicHeading = !!headingPrefix && searchText.length > 0;
 		<div class="search-bar__row2">
 			<p class="search-bar__count" data-search-count>{totalResults} {resultsWord}</p>
 			{totalPages > 1 && (
-				<PaginationLink
+				<Pagination
 					currentPage={currentPage}
 					totalPages={totalPages}
 					basePath={basePath}
-					perPage={perPage}
 					variant={paginationVariant}
-				/>
+				>
+					<PerPageSelector slot="controls" perPage={perPage} idBase={basePath} />
+				</Pagination>
 			)}
 		</div>
 	</div>
@@ -233,7 +235,7 @@ const dynamicHeading = !!headingPrefix && searchText.length > 0;
 		color: var(--color-text);
 	}
 
-	.search-bar__row2 :global(.iot-hub-pagination) {
+	.search-bar__row2 :global(.tb-pagination) {
 		flex: 1 1 0;
 	}
 </style>
diff --git a/src/components/IotHub/iot-hub-dynamic-search.ts b/src/components/IotHub/iot-hub-dynamic-search.ts
index 11c339b041..2a0c5b4ff0 100644
--- a/src/components/IotHub/iot-hub-dynamic-search.ts
+++ b/src/components/IotHub/iot-hub-dynamic-search.ts
@@ -1,6 +1,7 @@
 import {
 	IOT_HUB_API_URL,
 	IOT_HUB_CATEGORIES,
+	IOT_HUB_STRINGS,
 	SEARCH_PAGE_SIZE,
 	DEFAULT_IOT_HUB_SORT_ID,
 	getCardVariant,
@@ -11,10 +12,16 @@ import {
 } from '@models/iot-hub';
 import { bindListingCard } from './iot-hub-listing-card-bind';
 import { getKnownSlugs } from './iot-hub-known-slugs';
-import {
-	updatePaginationDynamic,
-	updateResultsCount,
-} from './iot-hub-pagination-update';
+import { updatePagination } from '@components/Pagination/pagination-client';
+
+// Host-visible "N results" line next to the pagination.
+function updateResultsCount(countEl: HTMLElement, totalResults: number): void {
+	const word =
+		totalResults === 1
+			? IOT_HUB_STRINGS.searchPage.resultSingular
+			: IOT_HUB_STRINGS.searchPage.resultPlural;
+	countEl.textContent = `${totalResults} ${word}`;
+}
 
 // Shared dynamic-search pipeline used by the search page, the creator
 // page, the category pages, and any future surface that lists
@@ -50,7 +57,7 @@ import {
 // URL state: q / sort / page / pageSize are mirrored in the query string
 // via history.replaceState on every fetch. On load, any non-default value
 // triggers an immediate fetch and is reflected in the matching UI control
-// (SearchFilterBar input, IotHubSort selection, PaginationLink per-page).
+// (SearchFilterBar input, IotHubSort selection, Pagination per-page).
 
 const DEBOUNCE_MS = 300;
 const ITEM_TYPE_BY_TYPE = new Map(IOT_HUB_CATEGORIES.map((c) => [c.itemType, c]));
@@ -131,7 +138,7 @@ export function setupDynamicSearch(): void {
 	const input = root.querySelector<HTMLInputElement>('[data-search-input]');
 	const resultsContainer = root.querySelector<HTMLElement>('[data-search-results]');
 	const itemsWrap = root.querySelector<HTMLElement>('[data-search-items]');
-	const paginationNav = root.querySelector<HTMLElement>('[data-iot-hub-pagination]');
+	const paginationNav = root.querySelector<HTMLElement>('[data-tb-pagination]');
 	const countEl = root.querySelector<HTMLElement>('[data-search-count]');
 	const noResults = root.querySelector<HTMLElement>('[data-iot-hub-no-results]');
 	const fetchError = root.querySelector<HTMLElement>('[data-iot-hub-fetch-error]');
@@ -234,7 +241,7 @@ export function setupDynamicSearch(): void {
 		if (!target) return;
 		perPageRoot.querySelectorAll<HTMLButtonElement>('[data-per-page-option]').forEach((opt) => {
 			const isSelected = opt === target;
-			opt.classList.toggle('iot-hub-pagination__per-page-option--selected', isSelected);
+			opt.classList.toggle('tb-pagination__per-page-option--selected', isSelected);
 			opt.setAttribute('aria-pressed', String(isSelected));
 		});
 		const labelEl = perPageRoot.querySelector<HTMLElement>('[data-per-page-label]');
@@ -367,7 +374,7 @@ export function setupDynamicSearch(): void {
 			showFetchError(false);
 			renderResults(items);
 			if (paginationNav) {
-				updatePaginationDynamic(paginationNav, { currentPage, totalPages });
+				updatePagination(paginationNav, { currentPage, totalPages });
 			}
 			updateResultsCount(countEl!, body.totalElements ?? 0);
 		} catch (err) {
@@ -469,14 +476,14 @@ export function setupDynamicSearch(): void {
 		void refetch({ resetPage: true });
 	}) as EventListener);
 
-	root.addEventListener('iot-hub-page-size:change', ((e: CustomEvent) => {
+	root.addEventListener('tb-pagination:page-size-change', ((e: CustomEvent) => {
 		const next = Number.parseInt(e.detail?.perPage ?? '0', 10);
 		if (!Number.isFinite(next) || next <= 0) return;
 		pageSize = next;
 		void refetch({ resetPage: true });
 	}) as EventListener);
 
-	root.addEventListener('iot-hub-page:change', ((e: CustomEvent) => {
+	root.addEventListener('tb-pagination:page-change', ((e: CustomEvent) => {
 		const next = Number.parseInt(e.detail?.page ?? '0', 10);
 		if (!Number.isFinite(next) || next <= 0) return;
 		currentPage = next;
diff --git a/src/components/IotHub/iot-hub-pagination-update.ts b/src/components/IotHub/iot-hub-pagination-update.ts
deleted file mode 100644
index 9ab78cfc24..0000000000
--- a/src/components/IotHub/iot-hub-pagination-update.ts
+++ /dev/null
@@ -1,168 +0,0 @@
-// Runtime updater for PaginationLink. When the host (dynamic search page,
-// future dynamic category pages) flips a pagination nav into dynamic mode,
-// it calls `updatePaginationDynamic(nav, { currentPage, totalPages })` to
-// rebuild the page-number list with event-based buttons. Clicks dispatch
-// `iot-hub-page:change` { page } bubbling events on the nav root — the
-// host listens and refetches.
-
-import { IOT_HUB_STRINGS, formatPageSummary } from '@models/iot-hub';
-
-interface PaginationState {
-	currentPage: number;
-	totalPages: number;
-}
-
-// Same page-list algorithm as the static buildPages() in PaginationLink.astro
-// so the dynamic UI keeps the same ellipsis ranges users are used to.
-function buildPages(current: number, total: number): Array<number | 'ellipsis'> {
-	if (total <= 7) return Array.from({ length: total }, (_, i) => i + 1);
-	const result: Array<number | 'ellipsis'> = [1];
-	if (current > 3) result.push('ellipsis');
-	for (let p = Math.max(2, current - 1); p <= Math.min(total - 1, current + 1); p++) {
-		result.push(p);
-	}
-	if (current < total - 2) result.push('ellipsis');
-	result.push(total);
-	return result;
-}
-
-const CHEVRON_PATHS = {
-	left: 'm15 6-6 6 6 6',
-	right: 'm9 6 6 6-6 6',
-};
-
-function chevronSvgHtml(direction: 'left' | 'right'): string {
-	return `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="${CHEVRON_PATHS[direction]}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg>`;
-}
-
-// <button> factories. UA button defaults (font-family, appearance,
-// :disabled colour) are reset in `@mixin pagination-btn` so dynamic-mode
-// controls render visually identical to their static <a> counterparts.
-// `.is-disabled` / `.is-current` classes block clicks via pointer-events
-// rather than the `disabled` attribute (which would apply the UA disabled
-// colour and fight `.is-current`'s accent background).
-
-function makeChevron(
-	direction: 'left' | 'right',
-	enabled: boolean,
-	targetPage: number,
-	label: string
-): HTMLElement {
-	const btn = document.createElement('button');
-	btn.type = 'button';
-	btn.className = `iot-hub-pagination__chevron${enabled ? '' : ' is-disabled'}`;
-	btn.setAttribute('aria-label', label);
-	if (!enabled) btn.setAttribute('aria-disabled', 'true');
-	btn.innerHTML = chevronSvgHtml(direction);
-	btn.addEventListener('click', () => {
-		if (!enabled) return;
-		dispatchPageChange(btn, targetPage);
-	});
-	return btn;
-}
-
-function makePageButton(page: number, isCurrent: boolean): HTMLElement {
-	const btn = document.createElement('button');
-	btn.type = 'button';
-	btn.className = `iot-hub-pagination__page${isCurrent ? ' is-current' : ''}`;
-	if (isCurrent) btn.setAttribute('aria-current', 'page');
-	btn.textContent = String(page);
-	btn.addEventListener('click', () => {
-		if (isCurrent) return;
-		dispatchPageChange(btn, page);
-	});
-	return btn;
-}
-
-function dispatchPageChange(el: HTMLElement, page: number): void {
-	el.dispatchEvent(
-		new CustomEvent('iot-hub-page:change', {
-			detail: { page },
-			bubbles: true,
-		})
-	);
-}
-
-export function updatePaginationDynamic(
-	nav: HTMLElement,
-	{ currentPage, totalPages }: PaginationState
-): void {
-	nav.dataset.dynamicMode = 'true';
-
-	// Rebuild the "numbers" list (desktop layout).
-	const numbersList = nav.querySelector<HTMLUListElement>(
-		'.iot-hub-pagination__pages--numbers'
-	);
-	if (numbersList) {
-		numbersList.replaceChildren();
-		const prevLi = document.createElement('li');
-		prevLi.appendChild(
-			makeChevron(
-				'left',
-				currentPage > 1,
-				currentPage - 1,
-				IOT_HUB_STRINGS.pagination.prevPageAriaLabel
-			)
-		);
-		numbersList.appendChild(prevLi);
-		for (const item of buildPages(currentPage, totalPages)) {
-			const li = document.createElement('li');
-			if (item === 'ellipsis') {
-				li.className = 'iot-hub-pagination__ellipsis';
-				li.setAttribute('aria-hidden', 'true');
-				li.textContent = '…';
-			} else {
-				li.appendChild(makePageButton(item, item === currentPage));
-			}
-			numbersList.appendChild(li);
-		}
-		const nextLi = document.createElement('li');
-		nextLi.appendChild(
-			makeChevron(
-				'right',
-				currentPage < totalPages,
-				currentPage + 1,
-				IOT_HUB_STRINGS.pagination.nextPageAriaLabel
-			)
-		);
-		numbersList.appendChild(nextLi);
-	}
-
-	// Rebuild the compact summary row (mobile layout).
-	const compact = nav.querySelector<HTMLElement>(
-		'.iot-hub-pagination__pages--compact'
-	);
-	if (compact) {
-		compact.replaceChildren();
-		compact.appendChild(
-			makeChevron(
-				'left',
-				currentPage > 1,
-				currentPage - 1,
-				IOT_HUB_STRINGS.pagination.prevPageAriaLabel
-			)
-		);
-		const summary = document.createElement('span');
-		summary.className = 'iot-hub-pagination__summary';
-		summary.textContent = formatPageSummary(currentPage, totalPages);
-		compact.appendChild(summary);
-		compact.appendChild(
-			makeChevron(
-				'right',
-				currentPage < totalPages,
-				currentPage + 1,
-				IOT_HUB_STRINGS.pagination.nextPageAriaLabel
-			)
-		);
-	}
-}
-
-// Set the host-visible "totalResults" line (the host calls
-// `updatePaginationDynamic` separately to rebuild the page list).
-export function updateResultsCount(countEl: HTMLElement, totalResults: number): void {
-	const word =
-		totalResults === 1
-			? IOT_HUB_STRINGS.searchPage.resultSingular
-			: IOT_HUB_STRINGS.searchPage.resultPlural;
-	countEl.textContent = `${totalResults} ${word}`;
-}
diff --git a/src/components/Pagination/Pagination.astro b/src/components/Pagination/Pagination.astro
new file mode 100644
index 0000000000..128b95ba41
--- /dev/null
+++ b/src/components/Pagination/Pagination.astro
@@ -0,0 +1,366 @@
+---
+// Site-wide pagination. Design contract:
+//   - This component renders the pagination UI and reports interactions
+//     (clicks as navigations in link mode, events in interactive mode) —
+//     URL state, scrolling, data fetching, and persistence belong to the
+//     consumer. Keep them there.
+//   - Surface-specific extras compose in via the "controls" slot from the
+//     consumer's own files (so their script/styles ship only where used).
+//     A surface-specific prop on this component is a signal to fork the
+//     shell instead (keep pagination-shared.ts + pagination-client.ts).
+//   - Shared by: /blog, /case-studies, /device-library, /partners/hardware,
+//     and the /iot-hub category/search/creator pages — when changing this
+//     file, spot-check more than one of them.
+import Chevron from '@components/Chevron.astro';
+import { buildPages, formatPageSummary, PAGINATION_STRINGS } from './pagination-shared';
+
+interface Props {
+	currentPage?: number;
+	totalPages?: number;
+	/**
+	 * Link mode: when set, page numbers render as real anchors — page 1 is
+	 * `basePath` itself, page N is `${basePath}N/`. When absent the component
+	 * renders in interactive mode: buttons that dispatch bubbling
+	 * `tb-pagination:page-change` { page } events (see pagination-client.ts,
+	 * whose `updatePagination()` rebuilds this markup after every change).
+	 */
+	basePath?: string;
+	/**
+	 * Layout variant:
+	 *   - 'centered' (default) — page-numbers centred, items-per-page
+	 *     absolutely pinned to the right edge.
+	 *   - 'right' — everything right-aligned in a single flex row, items-
+	 *     per-page sits inline after the page numbers.
+	 */
+	variant?: 'centered' | 'right';
+	/** Render hidden — for client-driven surfaces that unhide via JS. */
+	hidden?: boolean;
+	ariaLabel?: string;
+	prevLabel?: string;
+	nextLabel?: string;
+	class?: string;
+}
+
+const {
+	currentPage = 1,
+	totalPages = 1,
+	basePath,
+	variant = 'centered',
+	hidden = false,
+	ariaLabel = PAGINATION_STRINGS.ariaLabel,
+	prevLabel = PAGINATION_STRINGS.prevPageAriaLabel,
+	nextLabel = PAGINATION_STRINGS.nextPageAriaLabel,
+	class: className = '',
+} = Astro.props;
+
+const isLinkMode = typeof basePath === 'string';
+const pageUrl = (n: number): string => (n === 1 ? basePath! : `${basePath}${n}/`);
+
+const items = buildPages(currentPage, totalPages);
+const hasPrev = currentPage > 1;
+const hasNext = currentPage < totalPages;
+
+---
+
+<nav
+	class:list={['tb-pagination', `tb-pagination--${variant}`, className]}
+	aria-label={ariaLabel}
+	data-tb-pagination
+	data-prev-label={prevLabel}
+	data-next-label={nextLabel}
+	hidden={hidden}
+>
+	<div class="tb-pagination__pages-wrap">
+		<ul class="tb-pagination__pages tb-pagination__pages--numbers">
+			<li>
+				{
+					isLinkMode && hasPrev ? (
+						<a
+							class="tb-pagination__chevron"
+							href={pageUrl(currentPage - 1)}
+							rel="prev"
+							aria-label={prevLabel}
+						>
+							<Chevron direction="left" size={24} />
+						</a>
+					) : !isLinkMode ? (
+						<button
+							type="button"
+							class:list={['tb-pagination__chevron', !hasPrev && 'is-disabled']}
+							aria-label={prevLabel}
+							aria-disabled={!hasPrev ? 'true' : undefined}
+							data-nav-role="prev"
+						>
+							<Chevron direction="left" size={24} />
+						</button>
+					) : (
+						<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
+							<Chevron direction="left" size={24} />
+						</span>
+					)
+				}
+			</li>
+			{
+				items.map((item) =>
+					item === 'ellipsis' ? (
+						<li class="tb-pagination__ellipsis" aria-hidden="true">
+							…
+						</li>
+					) : (
+						<li>
+							{isLinkMode ? (
+								<a
+									class={`tb-pagination__page${item === currentPage ? ' is-current' : ''}`}
+									href={pageUrl(item)}
+									aria-current={item === currentPage ? 'page' : undefined}
+								>
+									{item}
+								</a>
+							) : (
+								<button
+									type="button"
+									class={`tb-pagination__page${item === currentPage ? ' is-current' : ''}`}
+									aria-current={item === currentPage ? 'page' : undefined}
+									data-nav-role={`page-${item}`}
+								>
+									{item}
+								</button>
+							)}
+						</li>
+					)
+				)
+			}
+			<li>
+				{
+					isLinkMode && hasNext ? (
+						<a
+							class="tb-pagination__chevron"
+							href={pageUrl(currentPage + 1)}
+							rel="next"
+							aria-label={nextLabel}
+						>
+							<Chevron direction="right" size={24} />
+						</a>
+					) : !isLinkMode ? (
+						<button
+							type="button"
+							class:list={['tb-pagination__chevron', !hasNext && 'is-disabled']}
+							aria-label={nextLabel}
+							aria-disabled={!hasNext ? 'true' : undefined}
+							data-nav-role="next"
+						>
+							<Chevron direction="right" size={24} />
+						</button>
+					) : (
+						<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
+							<Chevron direction="right" size={24} />
+						</span>
+					)
+				}
+			</li>
+		</ul>
+		<div class="tb-pagination__pages tb-pagination__pages--compact">
+			{
+				isLinkMode && hasPrev ? (
+					<a
+						class="tb-pagination__chevron"
+						href={pageUrl(currentPage - 1)}
+						rel="prev"
+						aria-label={prevLabel}
+					>
+						<Chevron direction="left" size={24} />
+					</a>
+				) : (
+					<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
+						<Chevron direction="left" size={24} />
+					</span>
+				)
+			}
+			<span class="tb-pagination__summary">{formatPageSummary(currentPage, totalPages)}</span>
+			{
+				isLinkMode && hasNext ? (
+					<a
+						class="tb-pagination__chevron"
+						href={pageUrl(currentPage + 1)}
+						rel="next"
+						aria-label={nextLabel}
+					>
+						<Chevron direction="right" size={24} />
+					</a>
+				) : (
+					<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
+						<Chevron direction="right" size={24} />
+					</span>
+				)
+			}
+		</div>
+	</div>
+	{/* Consumer-supplied trailing controls (e.g. PerPageSelector). Slotting
+	    (instead of props) keeps each control's script+styles out of pages
+	    that don't use it: Astro bundles per import graph, not per render. */}
+	<slot name="controls" />
+</nav>
+
+{/* Global by necessity: runtime-built buttons (pagination-client.ts) can't
+    carry Astro's scoped attributes, so static and dynamic markup share these
+    class-based styles. The `tb-pagination` prefix is the leakage guard. */}
+<style is:global lang="scss">
+	@use '../../styles/_variables.scss' as *;
+
+	.tb-pagination {
+		position: relative;
+		// Establishes a stacking context (z-index !== auto) so the per-page
+		// popup floats above the page sections that follow the pagination in
+		// DOM order.
+		z-index: 5;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0 16px;
+		min-height: 40px;
+
+		@include media-down(sm) {
+			padding: 0 12px;
+		}
+
+		&[hidden] {
+			display: none;
+		}
+	}
+
+	// `right` variant — single right-aligned row. Used by surfaces where the
+	// centred layout would leave a big empty column to the left.
+	.tb-pagination--right {
+		justify-content: flex-end;
+		gap: 16px;
+		padding-right: 0;
+
+		.tb-pagination__pages-wrap {
+			flex: 0;
+		}
+
+		.tb-pagination__per-page {
+			position: relative;
+			top: auto;
+			right: auto;
+			transform: none;
+		}
+	}
+
+	.tb-pagination__pages-wrap {
+		display: flex;
+		justify-content: center;
+		flex: 1 1 0;
+	}
+
+	.tb-pagination__pages {
+		display: flex;
+		align-items: center;
+		gap: 1px;
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	.tb-pagination__pages--compact {
+		display: none;
+		gap: 8px;
+	}
+
+	@include media-down(lg) {
+		.tb-pagination__pages--numbers {
+			display: none;
+		}
+
+		.tb-pagination__pages--compact {
+			display: flex;
+		}
+	}
+
+	// Mixin (not %placeholder + @extend) because @extend doesn't reliably
+	// reach across `:global()` selectors after Astro's SCSS pipeline rewrites
+	// them. `font-family: inherit` / `appearance: none` / `cursor: pointer`
+	// are explicit so runtime <button> elements render visually identical to
+	// build-time <a> counterparts without UA defaults leaking in.
+	@mixin tb-pagination-btn {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 40px;
+		height: 40px;
+		padding: 8px;
+		border: none;
+		border-radius: 8px;
+		font-family: inherit;
+		font-size: 14px;
+		font-weight: $font-weight-semibold;
+		line-height: 24px;
+		text-decoration: none;
+		color: var(--color-text-secondary);
+		background: transparent;
+		appearance: none;
+		cursor: pointer;
+		transition: background $transition-fast, color $transition-fast;
+
+		svg {
+			display: block;
+		}
+	}
+
+	.tb-pagination__chevron {
+		@include tb-pagination-btn;
+
+		&:hover,
+		&:focus-visible {
+			background: var(--color-bg-light);
+			color: var(--color-text);
+		}
+
+		&.is-disabled {
+			opacity: 0.4;
+			pointer-events: none;
+		}
+	}
+
+	.tb-pagination__page {
+		@include tb-pagination-btn;
+		padding: 8px 16px;
+		color: var(--color-text);
+
+		&:hover,
+		&:focus-visible {
+			background: var(--color-bg-light);
+		}
+
+		&.is-current {
+			background: var(--color-brand);
+			color: var(--color-brand-contrast);
+			pointer-events: none;
+		}
+	}
+
+	.tb-pagination__ellipsis {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 40px;
+		height: 40px;
+		padding: 8px 16px;
+		font-size: 14px;
+		font-weight: $font-weight-semibold;
+		line-height: 24px;
+		color: var(--sl-color-gray-5);
+	}
+
+	.tb-pagination__summary {
+		display: inline-flex;
+		align-items: center;
+		height: 40px;
+		font-size: 14px;
+		font-weight: $font-weight-semibold;
+		line-height: 24px;
+		color: var(--color-text);
+		white-space: nowrap;
+	}
+
+</style>
diff --git a/src/components/Pagination/PerPageSelector.astro b/src/components/Pagination/PerPageSelector.astro
new file mode 100644
index 0000000000..d0e07ef6cc
--- /dev/null
+++ b/src/components/Pagination/PerPageSelector.astro
@@ -0,0 +1,294 @@
+---
+import { Icon } from 'astro-icon/components';
+import Chevron from '@components/Chevron.astro';
+import { PAGINATION_STRINGS } from './pagination-shared';
+
+interface Props {
+	/** Current items-per-page value; options are [n, 2n, 3n]. */
+	perPage: number;
+	/** Stable per-instance string (e.g. the page's basePath) for unique ids. */
+	idBase: string;
+}
+
+const { perPage, idBase } = Astro.props;
+
+const perPageOptions = [perPage, perPage * 2, perPage * 3];
+// Deterministic instance-unique label id (reproducible SSR output).
+const slug = idBase
+	.toLowerCase()
+	.replace(/[^a-z0-9]+/g, '-')
+	.replace(/^-+|-+$/g, '');
+const labelId = `tb-pagination-pp-${slug || 'nav'}`;
+---
+
+<div class="tb-pagination__per-page" data-per-page-root data-per-page={perPage}>
+	<span class="tb-pagination__per-page-label" id={labelId}>
+		{PAGINATION_STRINGS.perPageLabel}
+	</span>
+	<button
+		type="button"
+		class="tb-pagination__per-page-value"
+		data-per-page-button
+		aria-expanded="false"
+		aria-labelledby={labelId}
+	>
+		<span data-per-page-label>{perPage}</span>
+		<Chevron direction="down" />
+	</button>
+	<div
+		class="tb-pagination__per-page-popup"
+		hidden
+		data-per-page-popup
+		role="group"
+		aria-label="Items per page"
+	>
+		{
+			perPageOptions.map((n) => (
+				<button
+					type="button"
+					class:list={[
+						'tb-pagination__per-page-option',
+						n === perPage && 'tb-pagination__per-page-option--selected',
+					]}
+					data-per-page-option
+					data-per-page-value={n}
+					aria-pressed={n === perPage}
+				>
+					<span class="tb-pagination__per-page-option-text">{n}</span>
+					<Icon name="tabler:check" class="tb-pagination__per-page-option-check" size={24} />
+				</button>
+			))
+		}
+	</div>
+</div>
+
+{/* Global for consistency with the parent's .tb-pagination__* contract. */}
+<style is:global lang="scss">
+	@use '../../styles/_variables.scss' as *;
+
+	.tb-pagination__per-page {
+		position: absolute;
+		top: 50%;
+		right: 16px;
+		transform: translateY(-50%);
+		display: inline-flex;
+		align-items: center;
+		gap: 8px;
+		font-size: 14px;
+		line-height: 24px;
+		color: var(--color-text-muted);
+
+		@include media-down(lg) {
+			display: none;
+		}
+	}
+
+	.tb-pagination__per-page-label {
+		white-space: nowrap;
+	}
+
+	.tb-pagination__per-page-value {
+		display: inline-flex;
+		align-items: center;
+		gap: 8px;
+		min-height: 40px;
+		min-width: 72px;
+		padding: 8px 8px 8px 12px;
+		border: 1px solid var(--color-border);
+		border-radius: 8px;
+		color: var(--color-text);
+		font-family: inherit;
+		font-size: 14px;
+		line-height: 24px;
+		font-weight: $font-weight-normal;
+		cursor: pointer;
+		background: var(--color-bg-surface);
+		transition: background-color $transition-fast, border-color $transition-fast;
+
+		&:hover,
+		&[aria-expanded='true'] {
+			background: var(--sl-color-gray-6);
+		}
+
+		svg {
+			color: var(--color-text-secondary);
+		}
+	}
+
+	// Popup anchored below the button. `right: 0` keeps it aligned to the
+	// trigger's right edge so longer option labels expand leftward into the
+	// row's empty space rather than overflowing the viewport.
+	.tb-pagination__per-page-popup {
+		position: absolute;
+		top: calc(100% + 4px);
+		right: 0;
+		min-width: 100%;
+		display: flex;
+		flex-direction: column;
+		padding: 4px;
+		background: var(--color-bg-surface);
+		border: 1px solid var(--iot-hub-hairline, rgba(0, 0, 0, 0.12));
+		border-radius: 8px;
+		box-shadow:
+			0 1px 0.5px rgba(0, 0, 0, 0.12),
+			0 2px 0.5px rgba(0, 0, 0, 0.24);
+		// Within the .tb-pagination stacking context (z-index: 5 on the nav),
+		// this is the local stacking level — high enough to clear any other
+		// internal absolutely-positioned siblings.
+		z-index: 100;
+
+		[data-theme='dark'] & {
+			border-color: var(--color-border);
+		}
+
+		// 120ms decel enter curve; pivot top-right so the popup expands
+		// downward from the button corner.
+		transform-origin: top right;
+		animation: tb-pagination-per-page-enter 120ms cubic-bezier(0, 0, 0.2, 1);
+
+		&[hidden] {
+			display: none;
+		}
+	}
+
+	@keyframes tb-pagination-per-page-enter {
+		from {
+			transform: scaleY(0);
+			opacity: 0;
+		}
+		to {
+			transform: scaleY(1);
+			opacity: 1;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.tb-pagination__per-page-popup {
+			animation: none;
+		}
+	}
+
+	.tb-pagination__per-page-option {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		width: 100%;
+		padding: 8px 12px;
+		font-family: inherit;
+		font-size: 14px;
+		font-weight: $font-weight-semibold;
+		line-height: 24px;
+		color: var(--sl-color-gray-2);
+		background: transparent;
+		border: none;
+		border-radius: 5px;
+		cursor: pointer;
+		text-align: left;
+		transition: background-color $transition-fast;
+
+		&:hover {
+			background: var(--sl-color-gray-6);
+		}
+
+		&:focus-visible {
+			outline: 2px solid var(--color-primary);
+			outline-offset: -2px;
+		}
+	}
+
+	.tb-pagination__per-page-option-text {
+		flex: 1 1 0;
+		min-width: 0;
+	}
+
+	.tb-pagination__per-page-option-check {
+		flex-shrink: 0;
+		visibility: hidden;
+	}
+
+	.tb-pagination__per-page-option--selected {
+		background: var(--sl-color-gray-6);
+		color: var(--color-brand);
+
+		.tb-pagination__per-page-option-check {
+			visibility: visible;
+		}
+	}
+</style>
+
+<script>
+	// Items-per-page dropdown. Click toggles, option click commits + closes +
+	// dispatches `tb-pagination:page-size-change` { perPage } for the host's
+	// dynamic data pipeline to handle.
+
+	function setupPerPage(root: HTMLElement) {
+		if (root.dataset.perPageInited) return;
+		root.dataset.perPageInited = 'true';
+
+		const button = root.querySelector<HTMLButtonElement>('[data-per-page-button]');
+		const popup = root.querySelector<HTMLElement>('[data-per-page-popup]');
+		const label = root.querySelector<HTMLElement>('[data-per-page-label]');
+		if (!button || !popup || !label) return;
+
+		const options = Array.from(root.querySelectorAll<HTMLButtonElement>('[data-per-page-option]'));
+
+		function openPopup() {
+			popup!.hidden = false;
+			button!.setAttribute('aria-expanded', 'true');
+		}
+
+		function closePopup() {
+			popup!.hidden = true;
+			button!.setAttribute('aria-expanded', 'false');
+		}
+
+		button.addEventListener('click', (e) => {
+			e.stopPropagation();
+			if (popup.hidden) openPopup();
+			else closePopup();
+		});
+
+		for (const opt of options) {
+			opt.addEventListener('click', (e) => {
+				e.stopPropagation();
+				const value = Number.parseInt(opt.dataset.perPageValue ?? '0', 10);
+				if (!Number.isFinite(value) || value <= 0) return;
+				for (const o of options) {
+					const isSelected = o === opt;
+					o.classList.toggle('tb-pagination__per-page-option--selected', isSelected);
+					o.setAttribute('aria-pressed', String(isSelected));
+				}
+				label!.textContent = String(value);
+				root.dataset.perPage = String(value);
+				closePopup();
+				root.dispatchEvent(
+					new CustomEvent('tb-pagination:page-size-change', {
+						detail: { perPage: value },
+						bubbles: true,
+					})
+				);
+			});
+		}
+
+		document.addEventListener('click', (e) => {
+			if (!popup.hidden && !root.contains(e.target as Node)) closePopup();
+		});
+		root.addEventListener('keydown', (e) => {
+			if (e.key === 'Escape' && !popup.hidden) {
+				closePopup();
+				button!.focus();
+			}
+		});
+	}
+
+	function initAll() {
+		document.querySelectorAll<HTMLElement>('[data-per-page-root]').forEach(setupPerPage);
+	}
+
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', initAll);
+	} else {
+		initAll();
+	}
+	document.addEventListener('astro:page-load', initAll);
+</script>
diff --git a/src/components/Pagination/pagination-client.ts b/src/components/Pagination/pagination-client.ts
new file mode 100644
index 0000000000..ea40e743c2
--- /dev/null
+++ b/src/components/Pagination/pagination-client.ts
@@ -0,0 +1,151 @@
+// Runtime updater for Pagination.astro. Client-driven surfaces (filtered
+// grids, dynamic search) call `updatePagination(nav, state)` after every
+// filter/page change to rebuild the page-number list with event-emitting
+// buttons. Clicks dispatch a bubbling `tb-pagination:page-change` { page }
+// CustomEvent on the nav root — the host listens, updates its state, and
+// calls updatePagination again. The per-page dropdown (when enabled on the
+// component) dispatches `tb-pagination:page-size-change` { perPage } the
+// same way.
+
+import { buildPages, CHEVRON_PATHS, formatPageSummary, PAGINATION_STRINGS } from './pagination-shared';
+
+export interface PaginationState {
+	currentPage: number;
+	totalPages: number;
+	/** Hide the whole nav when there is only one page. Default false. */
+	hideOnSinglePage?: boolean;
+}
+
+function chevronSvgHtml(direction: 'left' | 'right'): string {
+	return `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="${CHEVRON_PATHS[direction]}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg>`;
+}
+
+// <button> factories. UA button defaults (font-family, appearance, :disabled
+// colour) are reset in the component's `pagination-btn` styles so runtime
+// buttons render identical to build-time markup. `.is-disabled` /
+// `.is-current` block clicks via pointer-events rather than the `disabled`
+// attribute (which would apply the UA disabled colour and fight the accent
+// background).
+
+function makeChevron(
+	direction: 'left' | 'right',
+	enabled: boolean,
+	targetPage: number,
+	label: string
+): HTMLElement {
+	const btn = document.createElement('button');
+	btn.type = 'button';
+	btn.className = `tb-pagination__chevron${enabled ? '' : ' is-disabled'}`;
+	btn.dataset.navRole = direction === 'left' ? 'prev' : 'next';
+	btn.setAttribute('aria-label', label);
+	if (!enabled) btn.setAttribute('aria-disabled', 'true');
+	btn.innerHTML = chevronSvgHtml(direction);
+	btn.addEventListener('click', () => {
+		if (!enabled) return;
+		dispatchPageChange(btn, targetPage);
+	});
+	return btn;
+}
+
+function makePageButton(page: number, isCurrent: boolean): HTMLElement {
+	const btn = document.createElement('button');
+	btn.type = 'button';
+	btn.className = `tb-pagination__page${isCurrent ? ' is-current' : ''}`;
+	btn.dataset.navRole = `page-${page}`;
+	if (isCurrent) btn.setAttribute('aria-current', 'page');
+	btn.textContent = String(page);
+	btn.addEventListener('click', () => {
+		if (isCurrent) return;
+		dispatchPageChange(btn, page);
+	});
+	return btn;
+}
+
+// replaceChildren() destroys the control the user just activated, which
+// would drop keyboard focus to <body> on every page change. Capture the
+// focused control's role before the rebuild and re-focus its successor.
+function capturedFocusRole(nav: HTMLElement): string | null {
+	const active = document.activeElement as HTMLElement | null;
+	if (!active || !nav.contains(active)) return null;
+	return active.dataset.navRole ?? null;
+}
+
+function restoreFocus(nav: HTMLElement, role: string | null): void {
+	if (!role) return;
+	const visible = (el: HTMLElement) => el.offsetParent !== null;
+	const candidates = [
+		...nav.querySelectorAll<HTMLElement>(`[data-nav-role="${role}"]`),
+		nav.querySelector<HTMLElement>('.tb-pagination__page.is-current'),
+	].filter((el): el is HTMLElement => !!el);
+	candidates.find(visible)?.focus();
+}
+
+function dispatchPageChange(el: HTMLElement, page: number): void {
+	el.dispatchEvent(
+		new CustomEvent('tb-pagination:page-change', {
+			detail: { page },
+			bubbles: true,
+		})
+	);
+}
+
+function navLabels(nav: HTMLElement): { prev: string; next: string } {
+	return {
+		prev: nav.dataset.prevLabel || PAGINATION_STRINGS.prevPageAriaLabel,
+		next: nav.dataset.nextLabel || PAGINATION_STRINGS.nextPageAriaLabel,
+	};
+}
+
+export function updatePagination(
+	nav: HTMLElement,
+	{ currentPage, totalPages, hideOnSinglePage = false }: PaginationState
+): void {
+	if (hideOnSinglePage) {
+		nav.hidden = totalPages <= 1;
+		if (nav.hidden) return;
+	}
+
+	const focusRole = capturedFocusRole(nav);
+	const labels = navLabels(nav);
+
+	// Rebuild the "numbers" list (desktop layout).
+	const numbersList = nav.querySelector<HTMLUListElement>('.tb-pagination__pages--numbers');
+	if (numbersList) {
+		numbersList.replaceChildren();
+		const prevLi = document.createElement('li');
+		prevLi.appendChild(makeChevron('left', currentPage > 1, currentPage - 1, labels.prev));
+		numbersList.appendChild(prevLi);
+		for (const item of buildPages(currentPage, totalPages)) {
+			const li = document.createElement('li');
+			if (item === 'ellipsis') {
+				li.className = 'tb-pagination__ellipsis';
+				li.setAttribute('aria-hidden', 'true');
+				li.textContent = '…';
+			} else {
+				li.appendChild(makePageButton(item, item === currentPage));
+			}
+			numbersList.appendChild(li);
+		}
+		const nextLi = document.createElement('li');
+		nextLi.appendChild(
+			makeChevron('right', currentPage < totalPages, currentPage + 1, labels.next)
+		);
+		numbersList.appendChild(nextLi);
+	}
+
+	// Rebuild the compact summary row (mobile layout).
+	const compact = nav.querySelector<HTMLElement>('.tb-pagination__pages--compact');
+	if (compact) {
+		compact.replaceChildren();
+		compact.appendChild(makeChevron('left', currentPage > 1, currentPage - 1, labels.prev));
+		const summary = document.createElement('span');
+		summary.className = 'tb-pagination__summary';
+		summary.textContent = formatPageSummary(currentPage, totalPages);
+		compact.appendChild(summary);
+		compact.appendChild(
+			makeChevron('right', currentPage < totalPages, currentPage + 1, labels.next)
+		);
+	}
+
+	restoreFocus(nav, focusRole);
+}
diff --git a/src/components/Pagination/pagination-shared.ts b/src/components/Pagination/pagination-shared.ts
new file mode 100644
index 0000000000..0426517ddc
--- /dev/null
+++ b/src/components/Pagination/pagination-shared.ts
@@ -0,0 +1,37 @@
+// Logic shared between Pagination.astro (build-time) and pagination-client.ts
+// (runtime rebuilds). Single source for the page-window algorithm and chevron
+// geometry so static and dynamic renders can never drift apart.
+
+export type PageItem = number | 'ellipsis';
+
+// ≤7 pages: all numbers. Otherwise: 1 … (current−1, current, current+1) … last.
+export function buildPages(current: number, total: number): PageItem[] {
+	if (total <= 7) {
+		return Array.from({ length: total }, (_, i) => i + 1);
+	}
+	const result: PageItem[] = [1];
+	if (current > 3) result.push('ellipsis');
+	for (let p = Math.max(2, current - 1); p <= Math.min(total - 1, current + 1); p++) {
+		result.push(p);
+	}
+	if (current < total - 2) result.push('ellipsis');
+	result.push(total);
+	return result;
+}
+
+// Same geometry as Chevron.astro (24px viewBox, 2px round stroke).
+export const CHEVRON_PATHS = {
+	left: 'm15 6-6 6 6 6',
+	right: 'm9 6 6 6-6 6',
+} as const;
+
+export function formatPageSummary(current: number, total: number): string {
+	return `Page ${current} of ${total}`;
+}
+
+export const PAGINATION_STRINGS = {
+	ariaLabel: 'Pagination',
+	prevPageAriaLabel: 'Previous page',
+	nextPageAriaLabel: 'Next page',
+	perPageLabel: 'Items per page:',
+} as const;
diff --git a/src/components/Partners/PartnerLibrary.astro b/src/components/Partners/PartnerLibrary.astro
index 5feb0ac3c1..20abdd8d7e 100644
--- a/src/components/Partners/PartnerLibrary.astro
+++ b/src/components/Partners/PartnerLibrary.astro
@@ -3,7 +3,7 @@ import { Icon } from 'astro-icon/components';
 import PartnerCard from './PartnerCard.astro';
 import PartnerFilterSidebar from './PartnerFilterSidebar.astro';
 import SearchBar from '../DeviceLibrary/SearchBar.astro';
-import Pagination from '../DeviceLibrary/Pagination.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
 import type { HardwarePartner } from '~/data/partners/types';
 
 interface Props {
@@ -79,11 +79,13 @@ const filterGroups = [
 			No partners match your filters.
 		</div>
 
-		<Pagination translations={{ previous: 'Previous', next: 'Next', page: 'Page', of: 'of' }} />
+		<Pagination hidden />
 	</div>
 </div>
 
 <script>
+	import { updatePagination } from '@components/Pagination/pagination-client';
+
 	type FilterKey = 'connectivity' | 'industry' | 'useCase' | 'hardwareTypes';
 
 	const FILTER_KEYS: FilterKey[] = ['connectivity', 'industry', 'useCase', 'hardwareTypes'];
@@ -244,15 +246,9 @@ const filterGroups = [
 		);
 		const searchInput = container.querySelector('#device-search') as HTMLInputElement;
 		const searchClearBtn = container.querySelector('#search-clear') as HTMLButtonElement;
-		const pagination = container.querySelector('#pagination') as HTMLElement;
-		const paginationPages = container.querySelector('#pagination-pages') as HTMLElement;
-		const paginationPrev = container.querySelector('#pagination-prev') as HTMLButtonElement;
-		const paginationNext = container.querySelector('#pagination-next') as HTMLButtonElement;
-		const paginationInfo = container.querySelector('#pagination-info') as HTMLElement;
-		const paginationCurrent = container.querySelector('#pagination-current') as HTMLElement;
-		const paginationTotal = container.querySelector('#pagination-total') as HTMLElement;
+		const paginationNav = container.querySelector('[data-tb-pagination]') as HTMLElement;
 
-		if (!partnerGrid || !partnerCountEl || !searchInput || !sidebar) return;
+		if (!partnerGrid || !partnerCountEl || !searchInput || !sidebar || !paginationNav) return;
 
 		const pageSize = parseInt(container.getAttribute('data-page-size') || '12', 10);
 		let currentPage = 1;
@@ -270,48 +266,6 @@ const filterGroups = [
 			return filters;
 		}
 
-		function renderPagination(currentPage: number, totalPages: number) {
-			if (totalPages <= 1) {
-				pagination.hidden = true;
-				paginationInfo.hidden = true;
-				return;
-			}
-
-			pagination.hidden = false;
-			paginationInfo.hidden = false;
-
-			paginationPrev.disabled = currentPage <= 1;
-			paginationNext.disabled = currentPage >= totalPages;
-
-			paginationCurrent.textContent = String(currentPage);
-			paginationTotal.textContent = String(totalPages);
-
-			const pages: (number | string)[] = [];
-			const maxVisible = 5;
-
-			if (totalPages <= maxVisible) {
-				for (let i = 1; i <= totalPages; i++) pages.push(i);
-			} else {
-				pages.push(1);
-				if (currentPage > 3) pages.push('...');
-				const start = Math.max(2, currentPage - 1);
-				const end = Math.min(totalPages - 1, currentPage + 1);
-				for (let i = start; i <= end; i++) {
-					if (!pages.includes(i)) pages.push(i);
-				}
-				if (currentPage < totalPages - 2) pages.push('...');
-				if (!pages.includes(totalPages)) pages.push(totalPages);
-			}
-
-			paginationPages.innerHTML = pages
-				.map((p) =>
-					typeof p === 'number'
-						? `<button type="button" class="page-btn${p === currentPage ? ' active' : ''}" data-page="${p}">${p}</button>`
-						: `<span class="page-ellipsis">${p}</span>`
-				)
-				.join('');
-		}
-
 		const allCards = readCards(partnerGrid);
 		const filterOptions = readFilterOptions(sidebar);
 
@@ -336,7 +290,11 @@ const filterGroups = [
 			updateFacets(filterOptions, computeFacetCounts(allCards, filters, query), filters);
 
 			currentPage = result.currentPage;
-			renderPagination(result.currentPage, result.totalPages);
+			updatePagination(paginationNav, {
+				currentPage: result.currentPage,
+				totalPages: result.totalPages,
+				hideOnSinglePage: true,
+			});
 			searchClearBtn.hidden = !searchInput.value;
 		}
 
@@ -367,34 +325,18 @@ const filterGroups = [
 			searchInput.focus();
 		});
 
-		paginationPrev?.addEventListener('click', () => {
-			if (currentPage > 1) {
-				currentPage--;
-				updateDisplay();
-				partnerGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
-			}
-		});
-
-		paginationNext?.addEventListener('click', () => {
-			currentPage++;
+		paginationNav.addEventListener('tb-pagination:page-change', (e) => {
+			currentPage = (e as CustomEvent<{ page: number }>).detail.page;
 			updateDisplay();
 			partnerGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
 		});
 
-		paginationPages?.addEventListener('click', (e) => {
-			const target = e.target as HTMLElement;
-			if (target.classList.contains('page-btn')) {
-				const page = parseInt(target.dataset.page || '1', 10);
-				if (page !== currentPage) {
-					currentPage = page;
-					updateDisplay();
-					partnerGrid.scrollIntoView({ behavior: 'smooth', block: 'start' });
-				}
-			}
-		});
-
 		const initialTotalPages = Math.ceil(allCards.length / pageSize);
-		renderPagination(1, initialTotalPages);
+		updatePagination(paginationNav, {
+			currentPage: 1,
+			totalPages: initialTotalPages,
+			hideOnSinglePage: true,
+		});
 	}
 
 	initPartnerLibrary();
@@ -488,6 +430,12 @@ const filterGroups = [
 		display: none;
 	}
 
+	// Grid → pagination gap the old shell carried; vanishes with the nav's
+	// own `display: none` when it hides on single-page results.
+	.partner-library-main :global(.tb-pagination) {
+		margin-top: 2rem;
+	}
+
 	@include media-down(md) {
 		.partner-library {
 			flex-direction: column;
diff --git a/src/models/iot-hub.ts b/src/models/iot-hub.ts
index dbf4f44275..204a636fe9 100644
--- a/src/models/iot-hub.ts
+++ b/src/models/iot-hub.ts
@@ -209,10 +209,6 @@ export const IOT_HUB_STRINGS = {
 		resultSingular: 'result',
 		resultPlural: 'results',
 	},
-	pagination: {
-		prevPageAriaLabel: 'Previous page',
-		nextPageAriaLabel: 'Next page',
-	},
 	installs: {
 		singular: 'install',
 		plural: 'installs',
@@ -233,11 +229,6 @@ export function formatInstalls(count: number): string {
 	return `${formatInstallCount(count)} ${word}`;
 }
 
-/** Compact pagination summary for the mobile layout, e.g. `Page 2 of 7`. */
-export function formatPageSummary(current: number, total: number): string {
-	return `Page ${current} of ${total}`;
-}
-
 // Maps raw subtype keys from the API (`timeseries`, `SIMPLE`, `CORE`, …)
 // to user-facing labels for the filter panel "Type" section.
 export const ITEM_SUBTYPE_LABELS: Partial<Record<IotHubItemType, Record<string, string>>> = {
diff --git a/src/pages/blog/index.astro b/src/pages/blog/index.astro
index e4e697d44a..69eadc0fd3 100644
--- a/src/pages/blog/index.astro
+++ b/src/pages/blog/index.astro
@@ -1,5 +1,6 @@
 ---
 import BlogLayout from '../../layouts/BlogLayout.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
 import { getCollection } from 'astro:content';
 import { getAuthor } from '~/data/blog/authors';
 import { Icon } from 'astro-icon/components';
@@ -227,7 +228,9 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 			</div>
 
 			{/* ── Pagination ── */}
-			<nav class="pagination" id="pagination" aria-label="Blog pagination"></nav>
+			<div class="blog-pagination">
+				<Pagination hidden ariaLabel="Blog pagination" />
+			</div>
 		</div>
 	</main>
 </BlogLayout>
@@ -235,11 +238,12 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 <script>
 	import EmblaCarousel from 'embla-carousel';
 	import Autoplay from 'embla-carousel-autoplay';
+	import { updatePagination } from '@components/Pagination/pagination-client';
 
 	const POSTS_PER_PAGE = 6;
 
 	const gridTop = document.getElementById('post-grid-top')!;
-	const pagination = document.getElementById('pagination')!;
+	const paginationNav = document.querySelector<HTMLElement>('[data-tb-pagination]')!;
 	const noPostsMsg = document.getElementById('no-posts')!;
 	const categoryChips = document.querySelectorAll('.category-chip') as NodeListOf<HTMLAnchorElement>;
 	const clearAll = document.getElementById('clear-all')!;
@@ -274,39 +278,6 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 		);
 	}
 
-	function renderPagination(totalItems: number) {
-		const totalPages = Math.ceil(totalItems / POSTS_PER_PAGE);
-		if (totalPages <= 1) { pagination.innerHTML = ''; return; }
-
-		const pages: (number | '...')[] = [];
-		if (totalPages <= 7) {
-			for (let i = 1; i <= totalPages; i++) pages.push(i);
-		} else {
-			pages.push(1);
-			if (currentPage > 3) pages.push('...');
-			for (let i = Math.max(2, currentPage - 1); i <= Math.min(totalPages - 1, currentPage + 1); i++) pages.push(i);
-			if (currentPage < totalPages - 2) pages.push('...');
-			pages.push(totalPages);
-		}
-
-		let html = '<div class="pagination__pages">';
-		for (const p of pages) {
-			if (p === '...') html += `<span class="pagination__ellipsis">&hellip;</span>`;
-			else if (p === currentPage) html += `<span class="pagination__page pagination__page--active">${p}</span>`;
-			else html += `<button class="pagination__page" data-page="${p}">${p}</button>`;
-		}
-		html += '</div>';
-
-		pagination.innerHTML = html;
-		pagination.querySelectorAll('[data-page]').forEach((btn) => {
-			btn.addEventListener('click', () => {
-				currentPage = parseInt((btn as HTMLElement).dataset.page!, 10);
-				render();
-				window.scrollTo({ top: gridTop.offsetTop - 120, behavior: 'smooth' });
-			});
-		});
-	}
-
 	function render() {
 		const filtered = getFilteredItems();
 		const total = filtered.length;
@@ -326,10 +297,16 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 		categoryChips.forEach((chip) => chip.classList.toggle('active', (chip.dataset.category || '') === currentCategory));
 		clearAll.style.display = currentCategory ? '' : 'none';
 
-		renderPagination(total);
+		updatePagination(paginationNav, { currentPage, totalPages, hideOnSinglePage: true });
 		updateUrl();
 	}
 
+	paginationNav.addEventListener('tb-pagination:page-change', (e) => {
+		currentPage = (e as CustomEvent<{ page: number }>).detail.page;
+		render();
+		window.scrollTo({ top: gridTop.offsetTop - 120, behavior: 'smooth' });
+	});
+
 	categoryChips.forEach((chip) => {
 		chip.addEventListener('click', (e) => {
 			e.preventDefault();
@@ -928,52 +905,13 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 
 	// ── Pagination ──
 
-	.pagination {
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		gap: var(--spacing-2);
+	// Outer spacing lives on the wrapper so it persists even when the shared
+	// nav hides itself on single-page results (matches the old empty-nav gap).
+	.blog-pagination {
 		margin-top: var(--spacing-10);
 		padding: 0 var(--spacing-5) var(--spacing-10);
 	}
 
-	.pagination__pages {
-		display: flex;
-		align-items: center;
-		gap: 2px;
-	}
-
-	.pagination__page {
-		font-size: $font-size-sm;
-		color: var(--color-text-secondary);
-		background: none;
-		border: none;
-		cursor: pointer;
-		width: 36px;
-		height: 36px;
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		border-radius: $radius-sm;
-		transition: all 0.15s;
-		appearance: none;
-		font-family: inherit;
-		&:hover { background: color-mix(in srgb, var(--color-primary) 6%, transparent); color: var(--color-primary); }
-	}
-
-	.pagination__page--active {
-		background: var(--color-primary) !important;
-		color: var(--sl-color-black) !important;
-		font-weight: $font-weight-medium;
-		cursor: default;
-	}
-
-	.pagination__ellipsis {
-		width: 36px;
-		text-align: center;
-		color: var(--color-text-muted);
-	}
-
 	// ── Community CTA ──
 
 	.community-cta {
diff --git a/src/pages/case-studies/index.astro b/src/pages/case-studies/index.astro
index b262624967..05180ab74f 100644
--- a/src/pages/case-studies/index.astro
+++ b/src/pages/case-studies/index.astro
@@ -1,6 +1,7 @@
 ---
 import BaseLayout from '@layouts/BaseLayout.astro';
 import NButton from '../../components/Landing/NButton.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
 import { Icon } from 'astro-icon/components';
 import { caseStudyCards, caseStudyCategories, featuredCard } from '@data/case-studies';
 
@@ -122,17 +123,7 @@ const filterValues = caseStudyCategories.map((cat) => ({
 		<div class="cs-no-results" id="cs-no-results" hidden>No case studies match your filters.</div>
 
 		<!-- Pagination -->
-		<nav class="cs-pagination" id="cs-pagination" hidden aria-label="Pagination">
-			<button type="button" class="cs-page-btn cs-page-prev" id="cs-page-prev" disabled>
-				<Icon name="tabler:chevron-left" class="cs-page-chevron" />
-				<span class="cs-page-btn-text">Previous</span>
-			</button>
-			<div class="cs-page-numbers" id="cs-page-numbers"></div>
-			<button type="button" class="cs-page-btn cs-page-next" id="cs-page-next" disabled>
-				<span class="cs-page-btn-text">Next</span>
-				<Icon name="tabler:chevron-right" class="cs-page-chevron" />
-			</button>
-		</nav>
+		<Pagination hidden class="cs-pagination-nav" />
 
 		<!-- Success story CTA -->
 		<div class="cs-success-cta" id="cs-success-cta">
@@ -146,6 +137,8 @@ const filterValues = caseStudyCategories.map((cat) => ({
 </BaseLayout>
 
 <script>
+	import { updatePagination } from '@components/Pagination/pagination-client';
+
 	interface CSCard {
 		el: HTMLElement;
 		slug: string;
@@ -173,7 +166,8 @@ const filterValues = caseStudyCategories.map((cat) => ({
 
 	function initCaseStudyIndex() {
 		const grid = document.getElementById('cs-card-grid');
-		if (!grid) return;
+		if (!grid || grid.dataset.inited) return;
+		grid.dataset.inited = 'true';
 
 		const PAGE_SIZE = 9;
 		let currentPage = 1;
@@ -185,10 +179,7 @@ const filterValues = caseStudyCategories.map((cat) => ({
 		const clearFilters = document.getElementById('cs-clear-filters') as HTMLButtonElement;
 		const pills = Array.from(document.querySelectorAll<HTMLElement>('.cs-filter-pill'));
 		const checkboxes = pills.map((pill) => pill.querySelector<HTMLInputElement>('input[type="checkbox"]')!);
-		const pagination = document.getElementById('cs-pagination')!;
-		const pageNumbers = document.getElementById('cs-page-numbers')!;
-		const pagePrev = document.getElementById('cs-page-prev') as HTMLButtonElement;
-		const pageNext = document.getElementById('cs-page-next') as HTMLButtonElement;
+		const paginationNav = document.querySelector<HTMLElement>('[data-tb-pagination]')!;
 		const successCta = document.getElementById('cs-success-cta')!;
 
 		const allCards = readCards(grid);
@@ -215,35 +206,6 @@ const filterValues = caseStudyCategories.map((cat) => ({
 			};
 		}
 
-		function renderPagination(current: number, total: number) {
-			pagination.hidden = total <= 1;
-			if (total <= 1) return;
-
-			pagePrev.disabled = current <= 1;
-			pageNext.disabled = current >= total;
-
-			const pages: (number | string)[] = [];
-			if (total <= 5) {
-				for (let i = 1; i <= total; i++) pages.push(i);
-			} else {
-				pages.push(1);
-				if (current > 3) pages.push('...');
-				const start = Math.max(2, current - 1);
-				const end = Math.min(total - 1, current + 1);
-				for (let i = start; i <= end; i++) pages.push(i);
-				if (current < total - 2) pages.push('...');
-				pages.push(total);
-			}
-
-			pageNumbers.innerHTML = pages
-				.map((p) =>
-					typeof p === 'number'
-						? `<button type="button" class="cs-num-btn${p === current ? ' active' : ''}" data-page="${p}">${p}</button>`
-						: `<span class="cs-page-ellipsis">${p}</span>`
-				)
-				.join('');
-		}
-
 		function saveState(query: string, categories: string[]) {
 			const state: Record<string, string> = {};
 			if (query) state.q = query;
@@ -269,7 +231,11 @@ const filterValues = caseStudyCategories.map((cat) => ({
 			successCta.style.display = result.currentPage >= result.totalPages ? '' : 'none';
 
 			currentPage = result.currentPage;
-			renderPagination(result.currentPage, result.totalPages);
+			updatePagination(paginationNav, {
+				currentPage: result.currentPage,
+				totalPages: result.totalPages,
+				hideOnSinglePage: true,
+			});
 			saveState(query, categories);
 		}
 
@@ -323,29 +289,12 @@ const filterValues = caseStudyCategories.map((cat) => ({
 			searchInput.focus();
 		});
 
-		pagePrev.addEventListener('click', () => {
-			if (currentPage > 1) {
-				currentPage--;
-				updateDisplay();
-			}
-		});
-
-		pageNext.addEventListener('click', () => {
-			currentPage++;
+		// No scroll on page change here — intentional.
+		paginationNav.addEventListener('tb-pagination:page-change', (e) => {
+			currentPage = (e as CustomEvent<{ page: number }>).detail.page;
 			updateDisplay();
 		});
 
-		pageNumbers.addEventListener('click', (e) => {
-			const target = e.target as HTMLElement;
-			if (target.classList.contains('cs-num-btn')) {
-				const page = parseInt(target.dataset.page || '1', 10);
-				if (page !== currentPage) {
-					currentPage = page;
-					updateDisplay();
-				}
-			}
-		});
-
 		restoreState();
 		updateDisplay();
 	}
@@ -779,91 +728,9 @@ const filterValues = caseStudyCategories.map((cat) => ({
 		color: var(--color-text-secondary);
 	}
 
-	// ─── Pagination ───
-	.cs-pagination {
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		gap: $spacing-2;
+	// ─── Pagination (shared component; page only sets spacing) ───
+	.cs-pagination-nav {
 		margin-top: $spacing-8;
-
-		&[hidden] {
-			display: none;
-		}
-	}
-
-	.cs-page-btn {
-		display: flex;
-		align-items: center;
-		gap: $spacing-1;
-		padding: 4px $spacing-3;
-		font-size: $font-size-sm;
-		border: 1px solid var(--color-border);
-		border-radius: $radius-sm;
-		background: var(--color-bg-surface);
-		color: var(--color-text);
-		cursor: pointer;
-		transition: border-color $transition-fast;
-
-		&:hover:not(:disabled) {
-			border-color: var(--color-primary);
-		}
-
-		&:disabled {
-			opacity: 0.5;
-			cursor: not-allowed;
-		}
-	}
-
-	.cs-page-chevron {
-		width: 16px;
-		height: 16px;
-	}
-
-	.cs-page-numbers {
-		display: flex;
-		align-items: center;
-		gap: $spacing-1;
-	}
-
-	.cs-num-btn {
-		min-width: 32px;
-		height: 32px;
-		padding: 0 $spacing-2;
-		font-size: $font-size-sm;
-		border: 1px solid var(--color-border);
-		border-radius: $radius-sm;
-		background: var(--color-bg-surface);
-		color: var(--color-text);
-		cursor: pointer;
-		transition:
-			border-color $transition-fast,
-			background-color $transition-fast;
-
-		&:hover {
-			border-color: var(--color-primary);
-		}
-
-		&.active {
-			background: var(--color-primary);
-			border-color: var(--color-primary);
-			color: #fff;
-		}
-	}
-
-	.cs-page-ellipsis {
-		padding: 0 $spacing-1;
-		color: var(--color-text-secondary);
-	}
-
-	@include media-down(sm) {
-		.cs-page-btn-text {
-			display: none;
-		}
-
-		.cs-page-btn {
-			padding: $spacing-2;
-		}
 	}
 
 	// ─── Success story CTA ───
diff --git a/src/pages/iot-hub/[category]/[...page].astro b/src/pages/iot-hub/[category]/[...page].astro
index e60601b8ec..e48c44061f 100644
--- a/src/pages/iot-hub/[category]/[...page].astro
+++ b/src/pages/iot-hub/[category]/[...page].astro
@@ -13,7 +13,8 @@ import ListingCard from '@components/IotHub/ListingCard.astro';
 import ListingCardTemplate from '@components/IotHub/ListingCardTemplate.astro';
 import ListingGrid from '@components/IotHub/ListingGrid.astro';
 import ListingsFilterBar from '@components/IotHub/ListingsFilterBar.astro';
-import PaginationLink from '@components/IotHub/PaginationLink.astro';
+import Pagination from '@components/Pagination/Pagination.astro';
+import PerPageSelector from '@components/Pagination/PerPageSelector.astro';
 import { getCollection } from 'astro:content';
 import {
 	IOT_HUB_CATEGORIES,
@@ -115,11 +116,13 @@ const searchPlaceholder = heroTitle
 								<p class="iot-hub-cat__empty">{IOT_HUB_STRINGS.emptyState}</p>
 							) : (
 								page.lastPage > 1 && (
-									<PaginationLink
+									<Pagination
 										currentPage={page.currentPage}
 										totalPages={page.lastPage}
 										basePath={basePath}
-									/>
+									>
+										<PerPageSelector slot="controls" perPage={PAGE_SIZE} idBase={basePath} />
+									</Pagination>
 								)
 							)
 						}

From 2f0e14070330a123fe9590c1da942a0b217b761b Mon Sep 17 00:00:00 2001
From: Ruslan <rvasylkiv@thingsboard.io>
Date: Thu, 18 Jun 2026 11:40:58 +0300
Subject: [PATCH 2/3] refactor(pagination): address PR #477 review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Decouple PerPageSelector from the nav: new PaginationBar wraps the nav
  and the selector as siblings, so hiding the nav on a single page (or
  fetch error) no longer strips the items-per-page control — closes the
  trap where raising page size to one page removed the only way to lower
  it again. (review #5)
- Enable hideOnSinglePage on the IoT Hub runtime path now that the
  selector survives the nav hiding; route error-hide to the bar. (#6)
- Extract per-page-client.ts (setPerPageValue/setupPerPage) so URL-restore
  stops re-implementing the selector's internal toggling. (#5)
- restoreFocus skips .is-disabled controls so boundary navigation lands on
  the current page, not a dead chevron. (#1)
- Collapse the four duplicated prev/next chevron branches into
  PaginationChevron.astro. (#3)
- Single chevron path map in chevron-paths.ts, shared by Chevron.astro and
  pagination-shared.ts. (#4)
- Guard pageUrl so it only builds a URL in link mode.
---
 src/components/Chevron.astro                  |  12 +-
 src/components/IotHub/SearchFilterBar.astro   |  13 +-
 .../IotHub/iot-hub-dynamic-search.ts          |  33 ++--
 src/components/Pagination/Pagination.astro    | 168 +++++-------------
 src/components/Pagination/PaginationBar.astro |  97 ++++++++++
 .../Pagination/PaginationChevron.astro        |  60 +++++++
 .../Pagination/PerPageSelector.astro          |  80 +--------
 .../Pagination/pagination-client.ts           |   9 +-
 .../Pagination/pagination-shared.ts           |   8 +-
 src/components/Pagination/per-page-client.ts  |  79 ++++++++
 src/components/chevron-paths.ts               |  11 ++
 src/pages/iot-hub/[category]/[...page].astro  |  11 +-
 12 files changed, 339 insertions(+), 242 deletions(-)
 create mode 100644 src/components/Pagination/PaginationBar.astro
 create mode 100644 src/components/Pagination/PaginationChevron.astro
 create mode 100644 src/components/Pagination/per-page-client.ts
 create mode 100644 src/components/chevron-paths.ts

diff --git a/src/components/Chevron.astro b/src/components/Chevron.astro
index 00922aa4af..9c7baa2329 100644
--- a/src/components/Chevron.astro
+++ b/src/components/Chevron.astro
@@ -1,17 +1,13 @@
 ---
+import { CHEVRON_PATHS, type ChevronDirection } from '@components/chevron-paths';
+
 interface Props {
-	direction: 'left' | 'right' | 'down';
+	direction: ChevronDirection;
 	size?: number;
 	class?: string;
 }
 
 const { direction, size = 20, class: className } = Astro.props;
-
-const paths: Record<Props['direction'], string> = {
-	left: 'm15 6-6 6 6 6',
-	right: 'm9 6 6 6-6 6',
-	down: 'm6 9 6 6 6-6',
-};
 ---
 
 <svg
@@ -23,7 +19,7 @@ const paths: Record<Props['direction'], string> = {
 	aria-hidden="true"
 >
 	<path
-		d={paths[direction]}
+		d={CHEVRON_PATHS[direction]}
 		stroke="currentColor"
 		stroke-width="2"
 		stroke-linecap="round"
diff --git a/src/components/IotHub/SearchFilterBar.astro b/src/components/IotHub/SearchFilterBar.astro
index 992ea1ec1f..0007635272 100644
--- a/src/components/IotHub/SearchFilterBar.astro
+++ b/src/components/IotHub/SearchFilterBar.astro
@@ -1,8 +1,7 @@
 ---
 import { IOT_HUB_STRINGS, SEARCH_PAGE_SIZE } from '@models/iot-hub';
 import IotHubSort from './IotHubSort.astro';
-import Pagination from '@components/Pagination/Pagination.astro';
-import PerPageSelector from '@components/Pagination/PerPageSelector.astro';
+import PaginationBar from '@components/Pagination/PaginationBar.astro';
 
 const T = IOT_HUB_STRINGS.searchPage;
 
@@ -89,14 +88,14 @@ const dynamicHeading = !!headingPrefix && searchText.length > 0;
 		<div class="search-bar__row2">
 			<p class="search-bar__count" data-search-count>{totalResults} {resultsWord}</p>
 			{totalPages > 1 && (
-				<Pagination
+				<PaginationBar
 					currentPage={currentPage}
 					totalPages={totalPages}
 					basePath={basePath}
+					perPage={perPage}
+					idBase={basePath}
 					variant={paginationVariant}
-				>
-					<PerPageSelector slot="controls" perPage={perPage} idBase={basePath} />
-				</Pagination>
+				/>
 			)}
 		</div>
 	</div>
@@ -235,7 +234,7 @@ const dynamicHeading = !!headingPrefix && searchText.length > 0;
 		color: var(--color-text);
 	}
 
-	.search-bar__row2 :global(.tb-pagination) {
+	.search-bar__row2 :global(.tb-pagination-bar) {
 		flex: 1 1 0;
 	}
 </style>
diff --git a/src/components/IotHub/iot-hub-dynamic-search.ts b/src/components/IotHub/iot-hub-dynamic-search.ts
index 2a0c5b4ff0..687a96d021 100644
--- a/src/components/IotHub/iot-hub-dynamic-search.ts
+++ b/src/components/IotHub/iot-hub-dynamic-search.ts
@@ -13,6 +13,7 @@ import {
 import { bindListingCard } from './iot-hub-listing-card-bind';
 import { getKnownSlugs } from './iot-hub-known-slugs';
 import { updatePagination } from '@components/Pagination/pagination-client';
+import { setPerPageValue } from '@components/Pagination/per-page-client';
 
 // Host-visible "N results" line next to the pagination.
 function updateResultsCount(countEl: HTMLElement, totalResults: number): void {
@@ -139,6 +140,10 @@ export function setupDynamicSearch(): void {
 	const resultsContainer = root.querySelector<HTMLElement>('[data-search-results]');
 	const itemsWrap = root.querySelector<HTMLElement>('[data-search-items]');
 	const paginationNav = root.querySelector<HTMLElement>('[data-tb-pagination]');
+	// The bar wraps the nav + the items-per-page selector. Error/no-data states
+	// hide the whole bar; a single page of results hides only the nav (via
+	// updatePagination's hideOnSinglePage) so the per-page control stays usable.
+	const paginationBar = root.querySelector<HTMLElement>('[data-tb-pagination-bar]');
 	const countEl = root.querySelector<HTMLElement>('[data-search-count]');
 	const noResults = root.querySelector<HTMLElement>('[data-iot-hub-no-results]');
 	const fetchError = root.querySelector<HTMLElement>('[data-iot-hub-fetch-error]');
@@ -188,9 +193,11 @@ export function setupDynamicSearch(): void {
 		if (show) {
 			resultsContainer!.replaceChildren();
 			noResults!.hidden = true;
-			if (paginationNav) paginationNav.hidden = true;
-		} else if (paginationNav) {
-			paginationNav.hidden = false;
+			// Hide the whole bar (nav + per-page) on error; the success path
+			// re-shows it and updatePagination re-applies the single-page rule.
+			if (paginationBar) paginationBar.hidden = true;
+		} else if (paginationBar) {
+			paginationBar.hidden = false;
 		}
 	}
 
@@ -234,19 +241,7 @@ export function setupDynamicSearch(): void {
 
 	function applyPageSizeToUi(size: number): void {
 		const perPageRoot = root!.querySelector<HTMLElement>('[data-per-page-root]');
-		if (!perPageRoot) return;
-		const target = perPageRoot.querySelector<HTMLButtonElement>(
-			`[data-per-page-option][data-per-page-value="${size}"]`
-		);
-		if (!target) return;
-		perPageRoot.querySelectorAll<HTMLButtonElement>('[data-per-page-option]').forEach((opt) => {
-			const isSelected = opt === target;
-			opt.classList.toggle('tb-pagination__per-page-option--selected', isSelected);
-			opt.setAttribute('aria-pressed', String(isSelected));
-		});
-		const labelEl = perPageRoot.querySelector<HTMLElement>('[data-per-page-label]');
-		if (labelEl) labelEl.textContent = String(size);
-		perPageRoot.dataset.perPage = String(size);
+		if (perPageRoot) setPerPageValue(perPageRoot, size);
 	}
 
 	// --- DOM builders ------------------------------------------------------
@@ -374,7 +369,11 @@ export function setupDynamicSearch(): void {
 			showFetchError(false);
 			renderResults(items);
 			if (paginationNav) {
-				updatePagination(paginationNav, { currentPage, totalPages });
+				// Hide the page-number nav when a filter narrows results to a
+				// single page, matching the other surfaces. Safe here because the
+				// per-page selector lives in the bar (sibling of the nav), so it
+				// stays visible — letting the user lower the page size again.
+				updatePagination(paginationNav, { currentPage, totalPages, hideOnSinglePage: true });
 			}
 			updateResultsCount(countEl!, body.totalElements ?? 0);
 		} catch (err) {
diff --git a/src/components/Pagination/Pagination.astro b/src/components/Pagination/Pagination.astro
index 128b95ba41..fdbb26dc8e 100644
--- a/src/components/Pagination/Pagination.astro
+++ b/src/components/Pagination/Pagination.astro
@@ -11,7 +11,7 @@
 //   - Shared by: /blog, /case-studies, /device-library, /partners/hardware,
 //     and the /iot-hub category/search/creator pages — when changing this
 //     file, spot-check more than one of them.
-import Chevron from '@components/Chevron.astro';
+import PaginationChevron from './PaginationChevron.astro';
 import { buildPages, formatPageSummary, PAGINATION_STRINGS } from './pagination-shared';
 
 interface Props {
@@ -25,14 +25,6 @@ interface Props {
 	 * whose `updatePagination()` rebuilds this markup after every change).
 	 */
 	basePath?: string;
-	/**
-	 * Layout variant:
-	 *   - 'centered' (default) — page-numbers centred, items-per-page
-	 *     absolutely pinned to the right edge.
-	 *   - 'right' — everything right-aligned in a single flex row, items-
-	 *     per-page sits inline after the page numbers.
-	 */
-	variant?: 'centered' | 'right';
 	/** Render hidden — for client-driven surfaces that unhide via JS. */
 	hidden?: boolean;
 	ariaLabel?: string;
@@ -45,7 +37,6 @@ const {
 	currentPage = 1,
 	totalPages = 1,
 	basePath,
-	variant = 'centered',
 	hidden = false,
 	ariaLabel = PAGINATION_STRINGS.ariaLabel,
 	prevLabel = PAGINATION_STRINGS.prevPageAriaLabel,
@@ -54,7 +45,10 @@ const {
 } = Astro.props;
 
 const isLinkMode = typeof basePath === 'string';
-const pageUrl = (n: number): string => (n === 1 ? basePath! : `${basePath}${n}/`);
+// Only meaningful in link mode; interactive callers pass the result as an
+// unused href, so return '' there rather than building a `undefined2/` string.
+const pageUrl = (n: number): string =>
+	isLinkMode ? (n === 1 ? basePath! : `${basePath}${n}/`) : '';
 
 const items = buildPages(currentPage, totalPages);
 const hasPrev = currentPage > 1;
@@ -63,7 +57,7 @@ const hasNext = currentPage < totalPages;
 ---
 
 <nav
-	class:list={['tb-pagination', `tb-pagination--${variant}`, className]}
+	class:list={['tb-pagination', className]}
 	aria-label={ariaLabel}
 	data-tb-pagination
 	data-prev-label={prevLabel}
@@ -73,32 +67,15 @@ const hasNext = currentPage < totalPages;
 	<div class="tb-pagination__pages-wrap">
 		<ul class="tb-pagination__pages tb-pagination__pages--numbers">
 			<li>
-				{
-					isLinkMode && hasPrev ? (
-						<a
-							class="tb-pagination__chevron"
-							href={pageUrl(currentPage - 1)}
-							rel="prev"
-							aria-label={prevLabel}
-						>
-							<Chevron direction="left" size={24} />
-						</a>
-					) : !isLinkMode ? (
-						<button
-							type="button"
-							class:list={['tb-pagination__chevron', !hasPrev && 'is-disabled']}
-							aria-label={prevLabel}
-							aria-disabled={!hasPrev ? 'true' : undefined}
-							data-nav-role="prev"
-						>
-							<Chevron direction="left" size={24} />
-						</button>
-					) : (
-						<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
-							<Chevron direction="left" size={24} />
-						</span>
-					)
-				}
+				<PaginationChevron
+					direction="left"
+					isLinkMode={isLinkMode}
+					enabled={hasPrev}
+					href={pageUrl(currentPage - 1)}
+					rel="prev"
+					label={prevLabel}
+					navRole="prev"
+				/>
 			</li>
 			{
 				items.map((item) =>
@@ -131,74 +108,41 @@ const hasNext = currentPage < totalPages;
 				)
 			}
 			<li>
-				{
-					isLinkMode && hasNext ? (
-						<a
-							class="tb-pagination__chevron"
-							href={pageUrl(currentPage + 1)}
-							rel="next"
-							aria-label={nextLabel}
-						>
-							<Chevron direction="right" size={24} />
-						</a>
-					) : !isLinkMode ? (
-						<button
-							type="button"
-							class:list={['tb-pagination__chevron', !hasNext && 'is-disabled']}
-							aria-label={nextLabel}
-							aria-disabled={!hasNext ? 'true' : undefined}
-							data-nav-role="next"
-						>
-							<Chevron direction="right" size={24} />
-						</button>
-					) : (
-						<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
-							<Chevron direction="right" size={24} />
-						</span>
-					)
-				}
+				<PaginationChevron
+					direction="right"
+					isLinkMode={isLinkMode}
+					enabled={hasNext}
+					href={pageUrl(currentPage + 1)}
+					rel="next"
+					label={nextLabel}
+					navRole="next"
+				/>
 			</li>
 		</ul>
 		<div class="tb-pagination__pages tb-pagination__pages--compact">
-			{
-				isLinkMode && hasPrev ? (
-					<a
-						class="tb-pagination__chevron"
-						href={pageUrl(currentPage - 1)}
-						rel="prev"
-						aria-label={prevLabel}
-					>
-						<Chevron direction="left" size={24} />
-					</a>
-				) : (
-					<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
-						<Chevron direction="left" size={24} />
-					</span>
-				)
-			}
+			<PaginationChevron
+				direction="left"
+				isLinkMode={isLinkMode}
+				enabled={hasPrev}
+				href={pageUrl(currentPage - 1)}
+				rel="prev"
+				label={prevLabel}
+				navRole="prev"
+				interactiveButton={false}
+			/>
 			<span class="tb-pagination__summary">{formatPageSummary(currentPage, totalPages)}</span>
-			{
-				isLinkMode && hasNext ? (
-					<a
-						class="tb-pagination__chevron"
-						href={pageUrl(currentPage + 1)}
-						rel="next"
-						aria-label={nextLabel}
-					>
-						<Chevron direction="right" size={24} />
-					</a>
-				) : (
-					<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
-						<Chevron direction="right" size={24} />
-					</span>
-				)
-			}
+			<PaginationChevron
+				direction="right"
+				isLinkMode={isLinkMode}
+				enabled={hasNext}
+				href={pageUrl(currentPage + 1)}
+				rel="next"
+				label={nextLabel}
+				navRole="next"
+				interactiveButton={false}
+			/>
 		</div>
 	</div>
-	{/* Consumer-supplied trailing controls (e.g. PerPageSelector). Slotting
-	    (instead of props) keeps each control's script+styles out of pages
-	    that don't use it: Astro bundles per import graph, not per render. */}
-	<slot name="controls" />
 </nav>
 
 {/* Global by necessity: runtime-built buttons (pagination-client.ts) can't
@@ -208,11 +152,6 @@ const hasNext = currentPage < totalPages;
 	@use '../../styles/_variables.scss' as *;
 
 	.tb-pagination {
-		position: relative;
-		// Establishes a stacking context (z-index !== auto) so the per-page
-		// popup floats above the page sections that follow the pagination in
-		// DOM order.
-		z-index: 5;
 		display: flex;
 		align-items: center;
 		justify-content: center;
@@ -228,25 +167,6 @@ const hasNext = currentPage < totalPages;
 		}
 	}
 
-	// `right` variant — single right-aligned row. Used by surfaces where the
-	// centred layout would leave a big empty column to the left.
-	.tb-pagination--right {
-		justify-content: flex-end;
-		gap: 16px;
-		padding-right: 0;
-
-		.tb-pagination__pages-wrap {
-			flex: 0;
-		}
-
-		.tb-pagination__per-page {
-			position: relative;
-			top: auto;
-			right: auto;
-			transform: none;
-		}
-	}
-
 	.tb-pagination__pages-wrap {
 		display: flex;
 		justify-content: center;
diff --git a/src/components/Pagination/PaginationBar.astro b/src/components/Pagination/PaginationBar.astro
new file mode 100644
index 0000000000..86f8b9b7ed
--- /dev/null
+++ b/src/components/Pagination/PaginationBar.astro
@@ -0,0 +1,97 @@
+---
+// Pagination row for surfaces that pair the page-number nav with an
+// items-per-page dropdown (IoT Hub). The selector is a SIBLING of the nav,
+// not slotted inside it, so hiding the nav on a single page (or on a fetch
+// error) leaves the per-page control reachable — without it, a user who
+// raised the page size enough to collapse results to one page would lose the
+// only control that could lower it again. This wrapper is the positioned
+// ancestor for the selector's popup and owns the centered/right layout that
+// used to live on the nav.
+import Pagination from './Pagination.astro';
+import PerPageSelector from './PerPageSelector.astro';
+
+interface Props {
+	currentPage: number;
+	totalPages: number;
+	basePath: string;
+	perPage: number;
+	/** Stable per-instance string (e.g. basePath) for unique selector ids. */
+	idBase: string;
+	/**
+	 * Layout variant:
+	 *   - 'centered' (default) — page numbers centred, items-per-page
+	 *     absolutely pinned to the right edge.
+	 *   - 'right' — everything right-aligned in a single flex row, items-per-
+	 *     page sits inline after the page numbers.
+	 */
+	variant?: 'centered' | 'right';
+	class?: string;
+}
+
+const {
+	currentPage,
+	totalPages,
+	basePath,
+	perPage,
+	idBase,
+	variant = 'centered',
+	class: className = '',
+} = Astro.props;
+---
+
+<div
+	class:list={['tb-pagination-bar', `tb-pagination-bar--${variant}`, className]}
+	data-tb-pagination-bar
+>
+	<Pagination currentPage={currentPage} totalPages={totalPages} basePath={basePath} />
+	<PerPageSelector perPage={perPage} idBase={idBase} />
+</div>
+
+<style is:global lang="scss">
+	@use '../../styles/_variables.scss' as *;
+
+	.tb-pagination-bar {
+		position: relative;
+		// Establishes a stacking context (z-index !== auto) so the per-page
+		// popup floats above the page sections that follow in DOM order.
+		z-index: 5;
+		display: flex;
+		align-items: center;
+		min-height: 40px;
+
+		&[hidden] {
+			display: none;
+		}
+	}
+
+	// `centered` — nav fills the row and centres its numbers; the per-page
+	// selector is taken out of flow and pinned to the right edge (set in
+	// PerPageSelector.astro), so it never shifts the centred numbers.
+	.tb-pagination-bar--centered {
+		justify-content: center;
+
+		.tb-pagination {
+			flex: 1 1 0;
+		}
+	}
+
+	// `right` — single right-aligned row. Used where the centred layout would
+	// leave a big empty column to the left. Nav shrinks to its numbers, the
+	// per-page selector flows inline after it.
+	.tb-pagination-bar--right {
+		justify-content: flex-end;
+		gap: 16px;
+
+		.tb-pagination {
+			flex: 0 0 auto;
+			padding-right: 0;
+		}
+
+		.tb-pagination__per-page {
+			position: relative;
+			top: auto;
+			right: auto;
+			transform: none;
+		}
+	}
+</style>
diff --git a/src/components/Pagination/PaginationChevron.astro b/src/components/Pagination/PaginationChevron.astro
new file mode 100644
index 0000000000..c5de07a376
--- /dev/null
+++ b/src/components/Pagination/PaginationChevron.astro
@@ -0,0 +1,60 @@
+---
+// A single prev/next chevron, rendered three ways so the four near-identical
+// copies in Pagination.astro (prev/next × numbers/compact rows) stay in sync:
+//   - link mode, enabled  → real <a> (crawlable, rel=prev/next)
+//   - interactive mode    → event-emitting <button> (data-nav-role)
+//   - otherwise           → inert <span> (link-mode boundary, or the compact
+//     row's interactive placeholder that pagination-client.ts swaps live)
+import Chevron from '@components/Chevron.astro';
+
+interface Props {
+	direction: 'left' | 'right';
+	isLinkMode: boolean;
+	/** Whether navigation in this direction is possible (hasPrev / hasNext). */
+	enabled: boolean;
+	/** Target href for link mode (unused in the other branches). */
+	href: string;
+	rel: 'prev' | 'next';
+	label: string;
+	navRole: 'prev' | 'next';
+	/**
+	 * Render an event-emitting <button> in interactive mode. The compact row
+	 * passes false: it ships an inert placeholder <span> that
+	 * pagination-client.ts replaces with a live button on first update.
+	 */
+	interactiveButton?: boolean;
+}
+
+const {
+	direction,
+	isLinkMode,
+	enabled,
+	href,
+	rel,
+	label,
+	navRole,
+	interactiveButton = true,
+} = Astro.props;
+---
+
+{
+	isLinkMode && enabled ? (
+		<a class="tb-pagination__chevron" href={href} rel={rel} aria-label={label}>
+			<Chevron direction={direction} size={24} />
+		</a>
+	) : !isLinkMode && interactiveButton ? (
+		<button
+			type="button"
+			class:list={['tb-pagination__chevron', !enabled && 'is-disabled']}
+			aria-label={label}
+			aria-disabled={!enabled ? 'true' : undefined}
+			data-nav-role={navRole}
+		>
+			<Chevron direction={direction} size={24} />
+		</button>
+	) : (
+		<span class="tb-pagination__chevron is-disabled" aria-hidden="true">
+			<Chevron direction={direction} size={24} />
+		</span>
+	)
+}
diff --git a/src/components/Pagination/PerPageSelector.astro b/src/components/Pagination/PerPageSelector.astro
index d0e07ef6cc..6cb60a92bb 100644
--- a/src/components/Pagination/PerPageSelector.astro
+++ b/src/components/Pagination/PerPageSelector.astro
@@ -132,9 +132,9 @@ const labelId = `tb-pagination-pp-${slug || 'nav'}`;
 		box-shadow:
 			0 1px 0.5px rgba(0, 0, 0, 0.12),
 			0 2px 0.5px rgba(0, 0, 0, 0.24);
-		// Within the .tb-pagination stacking context (z-index: 5 on the nav),
-		// this is the local stacking level — high enough to clear any other
-		// internal absolutely-positioned siblings.
+		// Within the .tb-pagination-bar stacking context (z-index: 5 on the
+		// wrapper), this is the local stacking level — high enough to clear any
+		// other internal absolutely-positioned siblings.
 		z-index: 100;
 
 		[data-theme='dark'] & {
@@ -217,78 +217,12 @@ const labelId = `tb-pagination-pp-${slug || 'nav'}`;
 </style>
 
 <script>
-	// Items-per-page dropdown. Click toggles, option click commits + closes +
-	// dispatches `tb-pagination:page-size-change` { perPage } for the host's
-	// dynamic data pipeline to handle.
-
-	function setupPerPage(root: HTMLElement) {
-		if (root.dataset.perPageInited) return;
-		root.dataset.perPageInited = 'true';
-
-		const button = root.querySelector<HTMLButtonElement>('[data-per-page-button]');
-		const popup = root.querySelector<HTMLElement>('[data-per-page-popup]');
-		const label = root.querySelector<HTMLElement>('[data-per-page-label]');
-		if (!button || !popup || !label) return;
-
-		const options = Array.from(root.querySelectorAll<HTMLButtonElement>('[data-per-page-option]'));
-
-		function openPopup() {
-			popup!.hidden = false;
-			button!.setAttribute('aria-expanded', 'true');
-		}
-
-		function closePopup() {
-			popup!.hidden = true;
-			button!.setAttribute('aria-expanded', 'false');
-		}
-
-		button.addEventListener('click', (e) => {
-			e.stopPropagation();
-			if (popup.hidden) openPopup();
-			else closePopup();
-		});
-
-		for (const opt of options) {
-			opt.addEventListener('click', (e) => {
-				e.stopPropagation();
-				const value = Number.parseInt(opt.dataset.perPageValue ?? '0', 10);
-				if (!Number.isFinite(value) || value <= 0) return;
-				for (const o of options) {
-					const isSelected = o === opt;
-					o.classList.toggle('tb-pagination__per-page-option--selected', isSelected);
-					o.setAttribute('aria-pressed', String(isSelected));
-				}
-				label!.textContent = String(value);
-				root.dataset.perPage = String(value);
-				closePopup();
-				root.dispatchEvent(
-					new CustomEvent('tb-pagination:page-size-change', {
-						detail: { perPage: value },
-						bubbles: true,
-					})
-				);
-			});
-		}
-
-		document.addEventListener('click', (e) => {
-			if (!popup.hidden && !root.contains(e.target as Node)) closePopup();
-		});
-		root.addEventListener('keydown', (e) => {
-			if (e.key === 'Escape' && !popup.hidden) {
-				closePopup();
-				button!.focus();
-			}
-		});
-	}
-
-	function initAll() {
-		document.querySelectorAll<HTMLElement>('[data-per-page-root]').forEach(setupPerPage);
-	}
+	import { initPerPageSelectors } from './per-page-client';
 
 	if (document.readyState === 'loading') {
-		document.addEventListener('DOMContentLoaded', initAll);
+		document.addEventListener('DOMContentLoaded', initPerPageSelectors);
 	} else {
-		initAll();
+		initPerPageSelectors();
 	}
-	document.addEventListener('astro:page-load', initAll);
+	document.addEventListener('astro:page-load', initPerPageSelectors);
 </script>
diff --git a/src/components/Pagination/pagination-client.ts b/src/components/Pagination/pagination-client.ts
index ea40e743c2..c65fdcfca0 100644
--- a/src/components/Pagination/pagination-client.ts
+++ b/src/components/Pagination/pagination-client.ts
@@ -72,12 +72,17 @@ function capturedFocusRole(nav: HTMLElement): string | null {
 
 function restoreFocus(nav: HTMLElement, role: string | null): void {
 	if (!role) return;
-	const visible = (el: HTMLElement) => el.offsetParent !== null;
+	// Skip `.is-disabled` controls: navigating to the first/last page rebuilds
+	// that boundary chevron as disabled, and focusing it would park focus on a
+	// control the user can no longer activate. Falling through to the
+	// current-page button keeps focus on a live, meaningful target.
+	const focusable = (el: HTMLElement) =>
+		el.offsetParent !== null && !el.classList.contains('is-disabled');
 	const candidates = [
 		...nav.querySelectorAll<HTMLElement>(`[data-nav-role="${role}"]`),
 		nav.querySelector<HTMLElement>('.tb-pagination__page.is-current'),
 	].filter((el): el is HTMLElement => !!el);
-	candidates.find(visible)?.focus();
+	candidates.find(focusable)?.focus();
 }
 
 function dispatchPageChange(el: HTMLElement, page: number): void {
diff --git a/src/components/Pagination/pagination-shared.ts b/src/components/Pagination/pagination-shared.ts
index 0426517ddc..38dc23625a 100644
--- a/src/components/Pagination/pagination-shared.ts
+++ b/src/components/Pagination/pagination-shared.ts
@@ -19,11 +19,9 @@ export function buildPages(current: number, total: number): PageItem[] {
 	return result;
 }
 
-// Same geometry as Chevron.astro (24px viewBox, 2px round stroke).
-export const CHEVRON_PATHS = {
-	left: 'm15 6-6 6 6 6',
-	right: 'm9 6 6 6-6 6',
-} as const;
+// Re-exported so pagination-client.ts gets the chevron geometry from the same
+// source as the build-time <Chevron> renders — no second copy to drift.
+export { CHEVRON_PATHS } from '@components/chevron-paths';
 
 export function formatPageSummary(current: number, total: number): string {
 	return `Page ${current} of ${total}`;
diff --git a/src/components/Pagination/per-page-client.ts b/src/components/Pagination/per-page-client.ts
new file mode 100644
index 0000000000..d431fbb201
--- /dev/null
+++ b/src/components/Pagination/per-page-client.ts
@@ -0,0 +1,79 @@
+// Items-per-page dropdown behavior, shared between PerPageSelector.astro
+// (the inline init) and host pipelines that need to reflect a restored page
+// size back into the control (e.g. iot-hub-dynamic-search's `?pageSize=`
+// restore). Keeping the option-selection logic here means it lives in one
+// place instead of being re-implemented against PerPageSelector's internal
+// DOM by every consumer.
+
+// Reflect `value` as the selected option: toggle the selected class +
+// aria-pressed across all options, update the trigger label, and store the
+// value on the root's dataset. Does NOT dispatch an event — callers decide
+// whether a programmatic change should notify the host (option clicks do;
+// URL restores don't).
+export function setPerPageValue(root: HTMLElement, value: number): void {
+	root.querySelectorAll<HTMLButtonElement>('[data-per-page-option]').forEach((opt) => {
+		const isSelected = Number.parseInt(opt.dataset.perPageValue ?? '', 10) === value;
+		opt.classList.toggle('tb-pagination__per-page-option--selected', isSelected);
+		opt.setAttribute('aria-pressed', String(isSelected));
+	});
+	const label = root.querySelector<HTMLElement>('[data-per-page-label]');
+	if (label) label.textContent = String(value);
+	root.dataset.perPage = String(value);
+}
+
+// Wire one selector instance. Click toggles the popup; an option click
+// commits via setPerPageValue, closes, and dispatches a bubbling
+// `tb-pagination:page-size-change` { perPage } for the host's data pipeline.
+export function setupPerPage(root: HTMLElement): void {
+	if (root.dataset.perPageInited) return;
+	root.dataset.perPageInited = 'true';
+
+	const button = root.querySelector<HTMLButtonElement>('[data-per-page-button]');
+	const popup = root.querySelector<HTMLElement>('[data-per-page-popup]');
+	if (!button || !popup) return;
+
+	const openPopup = () => {
+		popup.hidden = false;
+		button.setAttribute('aria-expanded', 'true');
+	};
+	const closePopup = () => {
+		popup.hidden = true;
+		button.setAttribute('aria-expanded', 'false');
+	};
+
+	button.addEventListener('click', (e) => {
+		e.stopPropagation();
+		if (popup.hidden) openPopup();
+		else closePopup();
+	});
+
+	for (const opt of root.querySelectorAll<HTMLButtonElement>('[data-per-page-option]')) {
+		opt.addEventListener('click', (e) => {
+			e.stopPropagation();
+			const value = Number.parseInt(opt.dataset.perPageValue ?? '0', 10);
+			if (!Number.isFinite(value) || value <= 0) return;
+			setPerPageValue(root, value);
+			closePopup();
+			root.dispatchEvent(
+				new CustomEvent('tb-pagination:page-size-change', {
+					detail: { perPage: value },
+					bubbles: true,
+				})
+			);
+		});
+	}
+
+	document.addEventListener('click', (e) => {
+		if (!popup.hidden && !root.contains(e.target as Node)) closePopup();
+	});
+	root.addEventListener('keydown', (e) => {
+		if (e.key === 'Escape' && !popup.hidden) {
+			closePopup();
+			button.focus();
+		}
+	});
+}
+
+export function initPerPageSelectors(): void {
+	document.querySelectorAll<HTMLElement>('[data-per-page-root]').forEach(setupPerPage);
+}
diff --git a/src/components/chevron-paths.ts b/src/components/chevron-paths.ts
new file mode 100644
index 0000000000..c643f46e8f
--- /dev/null
+++ b/src/components/chevron-paths.ts
@@ -0,0 +1,11 @@
+// SVG path data for the chevron icon (24px viewBox, 2px round stroke).
+// Single source for Chevron.astro and the runtime-built chevrons in
+// pagination-client.ts (which can't render the .astro component), so a redraw
+// can't leave build-time and runtime icons out of sync.
+export const CHEVRON_PATHS = {
+	left: 'm15 6-6 6 6 6',
+	right: 'm9 6 6 6-6 6',
+	down: 'm6 9 6 6 6-6',
+} as const;
+
+export type ChevronDirection = keyof typeof CHEVRON_PATHS;
diff --git a/src/pages/iot-hub/[category]/[...page].astro b/src/pages/iot-hub/[category]/[...page].astro
index e48c44061f..e459cf5d47 100644
--- a/src/pages/iot-hub/[category]/[...page].astro
+++ b/src/pages/iot-hub/[category]/[...page].astro
@@ -13,8 +13,7 @@ import ListingCard from '@components/IotHub/ListingCard.astro';
 import ListingCardTemplate from '@components/IotHub/ListingCardTemplate.astro';
 import ListingGrid from '@components/IotHub/ListingGrid.astro';
 import ListingsFilterBar from '@components/IotHub/ListingsFilterBar.astro';
-import Pagination from '@components/Pagination/Pagination.astro';
-import PerPageSelector from '@components/Pagination/PerPageSelector.astro';
+import PaginationBar from '@components/Pagination/PaginationBar.astro';
 import { getCollection } from 'astro:content';
 import {
 	IOT_HUB_CATEGORIES,
@@ -116,13 +115,13 @@ const searchPlaceholder = heroTitle
 								<p class="iot-hub-cat__empty">{IOT_HUB_STRINGS.emptyState}</p>
 							) : (
 								page.lastPage > 1 && (
-									<Pagination
+									<PaginationBar
 										currentPage={page.currentPage}
 										totalPages={page.lastPage}
 										basePath={basePath}
-									>
-										<PerPageSelector slot="controls" perPage={PAGE_SIZE} idBase={basePath} />
-									</Pagination>
+										perPage={PAGE_SIZE}
+										idBase={basePath}
+									/>
 								)
 							)
 						}

From 41b750602a5891fc5e14096322921f2939a6c95f Mon Sep 17 00:00:00 2001
From: Ruslan <rvasylkiv@thingsboard.io>
Date: Thu, 18 Jun 2026 13:35:04 +0300
Subject: [PATCH 3/3] refactor(pagination): explicit mode prop + 2nd-review
 polish

- Replace the implicit basePath-presence mode inference with an explicit
  discriminated-union `mode: 'link' | 'interactive'` prop. Illegal combos
  (basePath in interactive mode, hidden in link mode, missing mode) are now
  astro-check errors instead of silent runtime surprises. The runtime markup
  contract and updatePagination are untouched, so IoT Hub's SSR-link ->
  runtime-interactive hybrid is unaffected. (review #2)
- Centralize the compact 'Page X of Y' summary into PAGINATION_STRINGS as a
  {current}/{total} template so every user-facing string lives in one place.
- Document restoreFocus's display:none-only assumption behind the offsetParent
  visibility probe.
---
 src/components/Pagination/Pagination.astro    | 66 ++++++++++++-------
 src/components/Pagination/PaginationBar.astro |  2 +-
 .../Pagination/pagination-client.ts           |  8 ++-
 .../Pagination/pagination-shared.ts           |  8 ++-
 src/components/Partners/PartnerLibrary.astro  |  2 +-
 src/pages/blog/index.astro                    |  2 +-
 src/pages/case-studies/index.astro            |  2 +-
 7 files changed, 60 insertions(+), 30 deletions(-)

diff --git a/src/components/Pagination/Pagination.astro b/src/components/Pagination/Pagination.astro
index fdbb26dc8e..527bb22417 100644
--- a/src/components/Pagination/Pagination.astro
+++ b/src/components/Pagination/Pagination.astro
@@ -4,47 +4,67 @@
 //     (clicks as navigations in link mode, events in interactive mode) —
 //     URL state, scrolling, data fetching, and persistence belong to the
 //     consumer. Keep them there.
-//   - Surface-specific extras compose in via the "controls" slot from the
-//     consumer's own files (so their script/styles ship only where used).
-//     A surface-specific prop on this component is a signal to fork the
-//     shell instead (keep pagination-shared.ts + pagination-client.ts).
-//   - Shared by: /blog, /case-studies, /device-library, /partners/hardware,
-//     and the /iot-hub category/search/creator pages — when changing this
-//     file, spot-check more than one of them.
+//   - Two modes, picked by the required `mode` prop (a discriminated union, so
+//     the type only permits each mode's own props):
+//       * mode="link"        — real <a> anchors; `basePath` required.
+//       * mode="interactive" — event-emitting <button>s; `hidden` allowed;
+//         pagination-client.ts's updatePagination() rebuilds the list.
+//   - Shared by: /blog, /case-studies, /partners/hardware (interactive) and
+//     the /iot-hub category/search/creator pages via PaginationBar (link at
+//     SSR, interactive at runtime). When changing this file, spot-check more
+//     than one of them.
 import PaginationChevron from './PaginationChevron.astro';
 import { buildPages, formatPageSummary, PAGINATION_STRINGS } from './pagination-shared';
 
-interface Props {
+// Props common to both modes, intersected with one of the two mode arms. The
+// discriminated union means `astro check` rejects illegal combos at build time:
+// `basePath` in interactive mode, `hidden` in link mode, or a missing `mode`.
+type Props = {
 	currentPage?: number;
 	totalPages?: number;
-	/**
-	 * Link mode: when set, page numbers render as real anchors — page 1 is
-	 * `basePath` itself, page N is `${basePath}N/`. When absent the component
-	 * renders in interactive mode: buttons that dispatch bubbling
-	 * `tb-pagination:page-change` { page } events (see pagination-client.ts,
-	 * whose `updatePagination()` rebuilds this markup after every change).
-	 */
-	basePath?: string;
-	/** Render hidden — for client-driven surfaces that unhide via JS. */
-	hidden?: boolean;
 	ariaLabel?: string;
 	prevLabel?: string;
 	nextLabel?: string;
 	class?: string;
-}
+} & (
+	| {
+			/**
+			 * Link mode: page numbers render as real anchors — page 1 is
+			 * `basePath`, page N is `${basePath}N/`. Crawlable, rel=prev/next, SSG.
+			 */
+			mode: 'link';
+			basePath: string;
+			hidden?: never;
+	  }
+	| {
+			/**
+			 * Interactive mode: buttons that dispatch bubbling
+			 * `tb-pagination:page-change` { page } events (see pagination-client.ts,
+			 * whose `updatePagination()` rebuilds this markup after every change).
+			 */
+			mode: 'interactive';
+			basePath?: never;
+			/** Render hidden — for client-driven surfaces that unhide via JS. */
+			hidden?: boolean;
+	  }
+);
 
+// Narrow on `Astro.props.mode` directly — TS can't narrow a union through
+// destructuring, and basePath/hidden each live on only one arm.
+const props = Astro.props;
 const {
 	currentPage = 1,
 	totalPages = 1,
-	basePath,
-	hidden = false,
 	ariaLabel = PAGINATION_STRINGS.ariaLabel,
 	prevLabel = PAGINATION_STRINGS.prevPageAriaLabel,
 	nextLabel = PAGINATION_STRINGS.nextPageAriaLabel,
 	class: className = '',
-} = Astro.props;
+} = props;
+
+const isLinkMode = props.mode === 'link';
+const basePath = props.mode === 'link' ? props.basePath : undefined;
+const hidden = props.mode === 'interactive' ? (props.hidden ?? false) : false;
 
-const isLinkMode = typeof basePath === 'string';
 // Only meaningful in link mode; interactive callers pass the result as an
 // unused href, so return '' there rather than building a `undefined2/` string.
 const pageUrl = (n: number): string =>
diff --git a/src/components/Pagination/PaginationBar.astro b/src/components/Pagination/PaginationBar.astro
index 86f8b9b7ed..149adc1194 100644
--- a/src/components/Pagination/PaginationBar.astro
+++ b/src/components/Pagination/PaginationBar.astro
@@ -43,7 +43,7 @@ const {
 	class:list={['tb-pagination-bar', `tb-pagination-bar--${variant}`, className]}
 	data-tb-pagination-bar
 >
-	<Pagination currentPage={currentPage} totalPages={totalPages} basePath={basePath} />
+	<Pagination mode="link" currentPage={currentPage} totalPages={totalPages} basePath={basePath} />
 	<PerPageSelector perPage={perPage} idBase={idBase} />
 </div>
 
diff --git a/src/components/Pagination/pagination-client.ts b/src/components/Pagination/pagination-client.ts
index c65fdcfca0..dfbee2e97d 100644
--- a/src/components/Pagination/pagination-client.ts
+++ b/src/components/Pagination/pagination-client.ts
@@ -72,8 +72,12 @@ function capturedFocusRole(nav: HTMLElement): string | null {
 
 function restoreFocus(nav: HTMLElement, role: string | null): void {
 	if (!role) return;
-	// Skip `.is-disabled` controls: navigating to the first/last page rebuilds
-	// that boundary chevron as disabled, and focusing it would park focus on a
+	// Pick the visible row's control. `offsetParent === null` detects hidden
+	// here only because the numbers/compact rows are toggled with
+	// `display: none` (media query) — a row hidden via visibility/opacity/clip
+	// would slip through, so that toggle must stay on `display`.
+	// Also skip `.is-disabled`: navigating to the first/last page rebuilds that
+	// boundary chevron as disabled, and focusing it would park focus on a
 	// control the user can no longer activate. Falling through to the
 	// current-page button keeps focus on a live, meaningful target.
 	const focusable = (el: HTMLElement) =>
diff --git a/src/components/Pagination/pagination-shared.ts b/src/components/Pagination/pagination-shared.ts
index 38dc23625a..64d89a765f 100644
--- a/src/components/Pagination/pagination-shared.ts
+++ b/src/components/Pagination/pagination-shared.ts
@@ -24,7 +24,9 @@ export function buildPages(current: number, total: number): PageItem[] {
 export { CHEVRON_PATHS } from '@components/chevron-paths';
 
 export function formatPageSummary(current: number, total: number): string {
-	return `Page ${current} of ${total}`;
+	return PAGINATION_STRINGS.pageSummary
+		.replace('{current}', String(current))
+		.replace('{total}', String(total));
 }
 
 export const PAGINATION_STRINGS = {
@@ -32,4 +34,8 @@ export const PAGINATION_STRINGS = {
 	prevPageAriaLabel: 'Previous page',
 	nextPageAriaLabel: 'Next page',
 	perPageLabel: 'Items per page:',
+	// {current}/{total} placeholders so the compact summary stays a single
+	// translatable phrase (word order varies by language) and lives with the
+	// other labels rather than as an inline string in formatPageSummary.
+	pageSummary: 'Page {current} of {total}',
 } as const;
diff --git a/src/components/Partners/PartnerLibrary.astro b/src/components/Partners/PartnerLibrary.astro
index e4789554f4..76e07fa9e5 100644
--- a/src/components/Partners/PartnerLibrary.astro
+++ b/src/components/Partners/PartnerLibrary.astro
@@ -79,7 +79,7 @@ const filterGroups = [
 			No partners match your filters.
 		</div>
 
-		<Pagination hidden />
+		<Pagination mode="interactive" hidden />
 	</div>
 </div>
 
diff --git a/src/pages/blog/index.astro b/src/pages/blog/index.astro
index 69eadc0fd3..44014891a8 100644
--- a/src/pages/blog/index.astro
+++ b/src/pages/blog/index.astro
@@ -229,7 +229,7 @@ const blogUrl = new URL('/blog/', Astro.site).href;
 
 			{/* ── Pagination ── */}
 			<div class="blog-pagination">
-				<Pagination hidden ariaLabel="Blog pagination" />
+				<Pagination mode="interactive" hidden ariaLabel="Blog pagination" />
 			</div>
 		</div>
 	</main>
diff --git a/src/pages/case-studies/index.astro b/src/pages/case-studies/index.astro
index 05180ab74f..d6c4ca4253 100644
--- a/src/pages/case-studies/index.astro
+++ b/src/pages/case-studies/index.astro
@@ -123,7 +123,7 @@ const filterValues = caseStudyCategories.map((cat) => ({
 		<div class="cs-no-results" id="cs-no-results" hidden>No case studies match your filters.</div>
 
 		<!-- Pagination -->
-		<Pagination hidden class="cs-pagination-nav" />
+		<Pagination mode="interactive" hidden class="cs-pagination-nav" />
 
 		<!-- Success story CTA -->
 		<div class="cs-success-cta" id="cs-success-cta">