<?php

declare(strict_types=1);

namespace App\Shared\Domain\Contract;

/**
 * Contrat d'export d'une feuille de calcul tabulaire vers un binaire XLSX.
 *
 * Service GENERIQUE et reutilisable : il ne connait aucune entite metier. Le
 * module appelant decide QUOI exporter (en-tetes + lignes deja mappees) ; cette
 * interface decrit seulement COMMENT produire le fichier. Aucun module n'est
 * couple a une implementation concrete : on depend de ce contrat (dans Shared),
 * jamais l'inverse (regle ABSOLUE n°1).
 *
 * Implementee par App\Shared\Infrastructure\Export\PhpSpreadsheetExporter (on
 * ne la reference pas via @see pour ne pas creer un import Domain -> Infra).
 */
interface SpreadsheetExporterInterface
{
    /**
     * Genere un classeur XLSX a une feuille et retourne son contenu binaire.
     *
     * @param string                      $sheetTitle titre de l'onglet (assaini / tronque par l'implementation si besoin)
     * @param list<string>                $headers    libelles de la ligne d'en-tete (ligne 1)
     * @param iterable<list<null|scalar>> $rows       lignes de donnees ; chaque ligne est une liste de cellules alignee sur $headers
     *
     * @return string contenu binaire du fichier XLSX
     */
    public function export(string $sheetTitle, array $headers, iterable $rows): string;
}
