<?php

namespace App\Reports\Contracts;

use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
use Illuminate\Database\Query\Builder as QueryBuilder;
use Illuminate\Http\Request;

interface Report
{
    public function slug(): string;

    public function name(): string;

    public function description(): ?string;

    /**
     * Return an array describing input filters (type, label, default, options) for UI.
     * Example item: ['key' => 'from', 'type' => 'date', 'label' => 'Od', 'default' => today()]
     *
     * @return array<int, array<string, mixed>>
     */
    public function inputs(): array;

    /**
     * Return column definitions for the table and exports.
     * Example: [ ['key' => 'id', 'label' => '#'], ['key' => 'user', 'label' => 'Uporabnik'] ]
     *
     * @return array<int, array<string, mixed>>
     */
    public function columns(): array;

    /**
     * Build the data source query for the report based on validated filters.
     * Should return an Eloquent or Query builder.
     *
     * @param  array<string, mixed>  $filters
     * @return EloquentBuilder|QueryBuilder
     */
    public function query(array $filters);

    /**
     * Optional per-report authorization logic.
     */
    public function authorize(Request $request): void;

    /**
     * Execute the report and return a paginator for UI.
     *
     * @param  array<string, mixed>  $filters
     */
    public function paginate(array $filters, int $perPage = 25): LengthAwarePaginator;
}