<?php

declare(strict_types=1);

namespace CliqThemes\UI\Contracts;

/**
 * Describes a data source that can drive CRUD experiences in the admin UI.
 */
interface DataProvider
{
    /**
     * Returns an iterable collection of records for a list view.
     *
     * @param array<string,mixed> $args Arbitrary pagination, sorting, or filter arguments.
     *
     * @return iterable<array<string,mixed>>|
     *     \CliqThemes\UI\Data\PaginatedResult Iterable collection or paginated result.
     */
    public function list(array $args = []): iterable;

    /**
     * Retrieves a single record by its unique identifier.
     *
     * @param array<string,mixed>|string|int $identifier
     * @param array<string,mixed>            $context
     *
     * @return array<string,mixed>
     */
    public function retrieve($identifier, array $context = []): array;

    /**
     * Persists a new record with the provided payload.
     *
     * @param array<string,mixed> $payload
     * @param array<string,mixed> $context
     *
     * @return array<string,mixed> Newly created entity data.
     */
    public function create(array $payload, array $context = []): array;

    /**
     * Updates an existing record identified by the given key.
     *
     * @param array<string,mixed>|string|int $identifier
     * @param array<string,mixed>            $payload
     * @param array<string,mixed>            $context
     *
     * @return array<string,mixed> Updated entity data.
     */
    public function update($identifier, array $payload, array $context = []): array;

    /**
     * Deletes the record identified by the given key.
     *
     * @param array<string,mixed>|string|int $identifier
     * @param array<string,mixed>            $context
     */
    public function delete($identifier, array $context = []): bool;

    /**
     * Provides column metadata for list table rendering.
     *
     * @return array<string,array<string,mixed>> Column definitions keyed by column id.
     */
    public function columns(): array;

    /**
     * Provides filter metadata to surface in the UI.
     *
     * @return array<string,array<string,mixed>>
     */
    public function filters(): array;
}
