Page numbers in display order; `null` is an ellipsis.
*/
function wpsubs_pager_page_range( int $current, int $total ): array {
$total = max( 1, $total );
$first = 1;
$last = $total;
$current = max( 1, min( $total, $current ) );
// Slide a 3-number window centred on the current page, excluding the pinned
// first/last pages so they don't show twice.
$near_start = max( 2, $current - 1 );
$near_end = min( $last - 1, $current + 1 );
$nearby = array();
for ( $i = $near_start; $i <= $near_end; $i++ ) {
$nearby[] = $i;
}
// Dedupe while preserving order (first/last may already be in $nearby).
$parts = array();
$seen = array();
$push = function ( int $n ) use ( &$parts, &$seen ) {
if ( ! isset( $seen[ $n ] ) ) {
$seen[ $n ] = true;
$parts[] = $n;
}
};
$push( $first );
foreach ( $nearby as $n ) {
$push( $n );
}
if ( $last > $first ) {
$push( $last );
}
// Emit ellipsis for gaps > 1 between consecutive visible numbers.
$range = array();
foreach ( $parts as $j => $p ) {
if ( $j > 0 ) {
$gap = $p - $parts[ $j - 1 ];
if ( 2 === $gap ) {
$range[] = $parts[ $j - 1 ] + 1; // single hidden page — surface it
} elseif ( $gap > 2 ) {
$range[] = null; // ellipsis
}
}
$range[] = $p;
}
return $range;
}
/**
* Render a WPSubscription paginator footer (info text + prev / next / numbered
* buttons + ellipsis). Single source of truth used by the subscriptions list
* (server-side) and the subscription details cards (hydrated by JS).
*
* Pair with `WPSubsPager` in `assets/js/admin-components.js` for auto-init on
* `.wpsubs-pager[data-wpsubs-pager]` elements. Pass `link_mode => 'cb'` from
* the details page so buttons trigger the JS controller instead of navigating.
*
* Markup follows the BEM classes defined in `admin-components.css`:
* .wpsubs-pagination
* .wpsubs-pagination__info
* .wpsubs-pagination__nav
* .wpsubs-pagination__btn (mods: --active | --disabled | --ellipsis)
*
* @param array $args {
* @type int $current Current page (1-indexed). Default 1.
* @type int $total Total number of pages. Default 1.
* @type bool $info Whether to render the "Showing X–Y of Z" info
* text alongside the buttons. Default false (only
* buttons are rendered).
* @type int $per_page Items per page (used when $info is true).
* @type int $item_count Total items (defaults to total * per_page).
* @type string $base_url Base URL for server-side links (link_mode=url).
* The component appends ?paged= and ?per_page= query args.
* Ignored if `link_url_callback` is provided.
* @type callable $link_url_callback Optional callable `function( int $page ): string`
* that returns the URL for a given page. When supplied,
* it replaces the default `add_query_arg( $base_url )` builder
* and lets callers (e.g. Pro templates) build URLs with
* admin_url() and arbitrary query args. The returned URL is
* not re-escaped — callers must escape with esc_url() before
* returning.
* @type string $link_mode 'url' (default, server ) or 'cb' (