<?php

declare(strict_types=1);

namespace PpPhp\Core\DataOps;

/**
 * One export format (CSV, Excel, JSON, …).
 *
 * Formats are self-describing so the whole pipeline — the Pages module's format
 * checkboxes, the generated toolbar menu, and export.php's server-side guard —
 * is driven from the registry instead of hardcoded lists. Adding a format means
 * dropping a class in core/DataOps/Formats and registering it; no build changes.
 */
interface ExportFormat
{
    /** Stable id used in URLs (?format=…) and in saved settings. */
    public static function id(): string;

    /** Human label for menus and settings ("Excel"). */
    public static function label(): string;

    /** [bootstrap-icon class, brand colour] for the toolbar entry. */
    public static function icon(): array;

    /** File extension of the produced download, without the dot. */
    public static function extension(): string;

    /** Content-Type sent with the download. */
    public static function contentType(): string;

    /**
     * Stream the export body (echo directly — headers are already sent).
     *
     * @param array<int, array<string, mixed>> $rows    result rows
     * @param array<string, string>            $columns column => label, in order
     * @param array<string, mixed>             $meta    caption, brand, table, generatedAt
     */
    public function write(array $rows, array $columns, array $meta): void;
}
