<?php

namespace App\Support;

use App\Models\Clients\Client;
use Illuminate\Support\Collection;

/**
 * Cómo se buscan clientes en un selector, **definido una sola vez**.
 *
 * Existe porque el mismo selector hace falta en el visor de peticiones y en el formulario
 * de un entorno, y lo que no puede divergir es **la consulta**: por qué campos busca,
 * cuántas devuelve y cómo se ordenan. Dos copias de eso acaban con una pantalla que
 * encuentra un cliente y otra que no, sin que nada lo avise — es lo que pasó con la
 * resolución de versiones repetida siete veces (MGR-024).
 *
 * El enganche a cada pantalla **no** vive aquí a propósito: una necesita `resetPage()` y la
 * otra no, y guardan el elegido en propiedades con nombres distintos. Meter eso en un trait
 * con dos ganchos sería más maquinaria que la que ahorra.
 *
 * **Busca por nombre y por `shortname`**, que es lo que ya hacían los buscadores de cliente
 * de las pantallas de licencias: quien tiene el shortname en la cabeza lo escribe.
 */
final class SugerenciasDeClientes
{
    /** Cuántas se ofrecen a la vez. Doce entran en pantalla sin desplazar. */
    public const CUANTAS = 12;

    /**
     * @return array{filas: Collection<int, Client>, total: int}
     *         `total` es cuántas coinciden en realidad, para poder decir cuántas quedan
     *         fuera: una lista recortada en silencio se lee como la lista completa.
     */
    public static function para(string $termino): array
    {
        $termino = trim($termino);

        $consulta = Client::query()
            ->when($termino !== '', fn ($q) => $q->where(
                fn ($sub) => $sub->where('name', 'like', '%' . $termino . '%')
                    ->orWhere('shortname', 'like', '%' . $termino . '%')
            ));

        return [
            // **Sin término se ofrecen los primeros, no una lista vacía.** Es un selector:
            // abrirlo y no ver nada hasta escribir dos letras es peor que el desplegable
            // completo que había antes. El mínimo de dos caracteres tiene sentido donde no
            // hay lista natural —469 componentes de plugin—, no aquí.
            'filas' => (clone $consulta)->orderBy('name')->limit(self::CUANTAS)->get(['id', 'name', 'shortname']),
            'total' => (clone $consulta)->count(),
        ];
    }
}