<?php
/**
 * The one paginated REST envelope.
 *
 * Every large list returns the same shape — `{ items, pagination }` — plus the
 * `X-WP-Total` / `X-WP-TotalPages` headers WordPress list clients already read.
 * A view never ships thousands of records; it ships one page and the counts.
 *
 * @package AiRankSuite
 */

declare(strict_types=1);

namespace AiRankSuite\Support;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

use WP_REST_Response;

final class Paginated {

	/**
	 * @param array<int, mixed> $items The current page of rows.
	 * @param int               $total Total rows across all pages.
	 * @param ListQuery         $query The query these rows answer.
	 */
	public static function response( array $items, int $total, ListQuery $query ): WP_REST_Response {
		$total    = max( 0, $total );
		$per_page = max( 1, $query->per_page );
		$pages    = (int) ceil( $total / $per_page );

		$response = new WP_REST_Response(
			array(
				'items'      => array_values( $items ),
				'pagination' => array(
					'page'        => $query->page,
					'per_page'    => $query->per_page,
					'total_items' => $total,
					'total_pages' => $pages,
				),
			)
		);
		$response->header( 'X-WP-Total', (string) $total );
		$response->header( 'X-WP-TotalPages', (string) $pages );
		return $response;
	}
}