<?php

namespace Storeplugin\PDFInvoice\Framework\Contracts;

defined('ABSPATH') || exit;

/**
 * Taxonomy Builder Interface
 *
 * Defines the public API for creating and configuring custom taxonomies.
 * Internal WordPress registration methods are marked with @internal in
 * the implementing class.
 *
 * @package Storeplugin\PDFInvoice\Framework\Contracts
 */
interface TaxonomyInterface
{
    /**
     * Create a new taxonomy instance
     *
     * @param string $taxonomy   Taxonomy slug (max 32 characters)
     * @param string $plural     Plural name for labels
     * @param string $textDomain Text domain for translations
     *
     * @return self
     */
    public static function create(string $taxonomy, string $plural, string $textDomain = ''): self;

    /**
     * Associate taxonomy with post types
     *
     * @param string|array $objectType Post type slug(s)
     *
     * @return self
     */
    public function objectType($objectType): self;

    /**
     * Set hierarchical structure
     *
     * @param bool $hierarchical Whether hierarchical (like categories)
     *
     * @return self
     */
    public function hierarchical(bool $hierarchical = true): self;

    /**
     * Show UI in admin
     *
     * @param bool $show Whether to show UI
     *
     * @return self
     */
    public function showUi(bool $show = true): self;

    /**
     * Show in admin menu
     *
     * @param bool $show Whether to show in menu
     *
     * @return self
     */
    public function showInMenu(bool $show = true): self;

    /**
     * Register as submenu under parent menu
     *
     * @param string $parentSlug Parent menu slug
     *
     * @return self
     */
    public function submenuOf(string $parentSlug): self;

    /**
     * Show in Quick Edit panel
     *
     * @param bool $show Whether to show in Quick Edit
     *
     * @return self
     */
    public function showInQuickEdit(bool $show = true): self;

    /**
     * Show as column in admin
     *
     * @param bool $show Whether to show admin column
     *
     * @return self
     */
    public function showAdminColumn(bool $show = true): self;

    /**
     * Enable/disable query var
     *
     * @param string|bool $query Query var name or true/false
     *
     * @return self
     */
    public function queryVar($query = true): self;

    /**
     * Configure rewrite rules
     *
     * @param array|bool $rewrite Rewrite configuration or true/false
     *
     * @return self
     */
    public function rewrite($rewrite = true): self;

    /**
     * Enable REST API support
     *
     * @param bool $show Whether to show in REST API
     *
     * @return self
     */
    public function showInRest(bool $show = true): self;

    /**
     * Set REST API base slug
     *
     * @param string $base REST base slug
     *
     * @return self
     */
    public function restBase(string $base): self;

    /**
     * Set REST API controller class
     *
     * @param string $controller Controller class name
     *
     * @return self
     */
    public function restControllerClass($controller): self;

    /**
     * Show in navigation menus
     *
     * @param bool $show Whether to show in nav menus
     *
     * @return self
     */
    public function showInNavMenus(bool $show = true): self;

    /**
     * Show tag cloud widget
     *
     * @param bool $show Whether to show tag cloud
     *
     * @return self
     */
    public function showTagcloud(bool $show = true): self;

    /**
     * Show in admin UI
     *
     * @param bool $show Whether to show in admin
     *
     * @return self
     */
    public function showAdmin(bool $show = true): self;

    /**
     * Set custom meta box callback
     *
     * @param callable|null $callback Meta box callback function
     *
     * @return self
     */
    public function metaBoxCb(?callable $callback): self;

    /**
     * Set custom capabilities
     *
     * @param array|null $capabilities Capabilities array
     *
     * @return self
     */
    public function capabilities(?array $capabilities): self;

    /**
     * Set update count callback
     *
     * @param callable|null $callback Update count callback
     *
     * @return self
     */
    public function updateCountCallback(?callable $callback): self;

    /**
     * Enable/disable sorting
     *
     * @param bool $sort Whether to enable sorting
     *
     * @return self
     */
    public function sort(bool $sort = true): self;

    /**
     * Register and initialize the taxonomy
     *
     * @return void
     */
    public function render(): void;
}
