<?php

declare(strict_types=1);

namespace PpPhp\Core\DataOps;

/**
 * One import source format (delimited text, JSON, XML, …).
 *
 * A reader turns an uploaded/pasted file into [header, rows]. Its extensions()
 * drive both the file-picker accept="" list and the server-side upload guard,
 * so enabling a format in the Pages module is all that is needed.
 */
interface ImportReader
{
    /** Stable id used in saved settings. */
    public static function id(): string;

    /** Human label ("Delimited text (CSV/TSV)"). */
    public static function label(): string;

    /** Lower-case file extensions this reader accepts, without the dot. */
    public static function extensions(): array;

    /** True when this reader can also accept pasted text (not just a file). */
    public static function supportsPaste(): bool;

    /**
     * Read a stored file into a header row plus data rows.
     *
     * @param array<string, mixed> $opts hasHeader, delimiter, …
     * @return array{0: list<string>, 1: list<list<string>>} [header, rows]
     */
    public function read(string $path, array $opts): array;
}
