<?php

namespace Storeplugin\PDFInvoice\Framework\Contracts;

defined('ABSPATH') || exit;

use Storeplugin\PDFInvoice\Framework\Contracts\DataSourceInterface;

/**
 * Table Builder Interface
 *
 * Defines the public API for building and registering WordPress list tables.
 * Internal WordPress callback methods are intentionally excluded to keep the API clean.
 *
 * @package Storeplugin\PDFInvoice\Framework\Contracts
 * @since 1.0.0
 */
interface TableInterface
{
    /**
     * Create a new instance.
     *
     * @param string      $singular
     * @param string      $plural
     * @param string|null $menuSlug
     *
     * @return self
     */
    public static function create( $singular, $plural, $menuSlug = null ): self;

    /**
     * Set the columns.
     *
     * @param array $columns
     *
     * @return self
     */
    public function withColumns( array $columns ): self;

    /**
     * Set the primary column.
     *
     * @param string $columnName
     *
     * @return self
     */
    public function withPrimaryColumn( $columnName ): self;

    /**
     * Set the sortable columns.
     *
     * @param array $sortable
     *
     * @return self
     */
    public function withSortableColumns( array $sortable ): self;

    /**
     * Set the data source.
     *
     * @param DataSourceInterface $dataSource
     *
     * @return self
     */
    public function fromDataSource( DataSourceInterface $dataSource ): self;

    /**
     * Set the bulk actions.
     *
     * @param array $actions
     *
     * @return self
     */
    public function withBulkActions( array $actions ): self;

    /**
     * Add a bulk action handler.
     *
     * @param string   $action
     * @param callable $handler
     *
     * @return self
     */
    public function addBulkActionHandler( $action, callable $handler ): self;

    /**
     * Enable search.
     *
     * @param bool $columns
     *
     * @return self
     */
    public function withSearch( $columns = true ): self;

    /**
     * Add a column renderer.
     *
     * @param string   $columnName
     * @param callable $callback
     *
     * @return self
     */
    public function addColumnRenderer( $columnName, callable $callback ): self;

    /**
     * Set the row actions.
     *
     * @param callable $callback
     *
     * @return self
     */
    public function withRowActions( callable $callback ): self;

    /**
     * Set the hidden columns.
     *
     * @param array $columns
     *
     * @return self
     */
    public function withHiddenColumns( array $columns ): self;

    /**
     * Set the pagination.
     *
     * @param int $perPage
     *
     * @return self
     */
    public function withPagination( $perPage ): self;

    /**
     * Set the table classes.
     *
     * @param array $classes
     *
     * @return self
     */
    public function withTableClasses( array $classes ): self;

    /**
     * Set the capability.
     *
     * @param string $capability
     *
     * @return self
     */
    public function withCapability( $capability ): self;

    /**
     * Set the description.
     *
     * @param string $description
     *
     * @return self
     */
    public function description( $description ): self;

    /**
     * Set the admin menu.
     *
     * @param string      $pageTitle
     * @param string      $menuTitle
     * @param string      $iconUrl
     * @param int|null    $position
     *
     * @return self
     */
    public function withAdminMenu( $pageTitle, $menuTitle, $iconUrl = '', $position = null ): self;

    /**
     * Hide the menu.
     *
     * @param bool $hide
     *
     * @return self
     */
    public function hideMenu( $hide = true ): self;

    /**
     * Set the admin submenu.
     *
     * @param string      $parentSlug
     * @param string      $pageTitle
     * @param string      $menuTitle
     * @param string|null $capability
     *
     * @return self
     */
    public function withAdminSubmenu( $parentSlug, $pageTitle, $menuTitle, $capability = null ): self;

    /**
     * Set the admin submenu for a post type.
     *
     * @param string      $postType
     * @param string|null $pageTitle
     * @param string|null $menuTitle
     * @param string|null $capability
     *
     * @return self
     */
    public function withAdminSubmenuPostType( $postType, $pageTitle = null, $menuTitle = null, $capability = null ): self;

    /**
     * Add a header callback.
     *
     * @param callable $callback
     *
     * @return self
     */
    public function addHeader( callable $callback ): self;

    /**
     * Add a footer callback.
     *
     * @param callable $callback
     *
     * @return self
     */
    public function addFooter( callable $callback ): self;

    /**
     * Enable drag and drop reordering.
     *
     * @param bool        $enabled
     * @param string|null $handleColumn
     *
     * @return self
     */
    public function draggable( $enabled = true, $handleColumn = null ): self;

    /**
     * Register the table with WordPress.
     *
     * @param int|null $priority Priority for the admin_menu hook.
     *
     * @return void
     */
    public function register( $priority = null ): void;
}
