<?php

namespace Storeplugin\PDFInvoice\Framework\Contracts;

defined('ABSPATH') || exit;

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

    /**
     * Set the post type description
     *
     * @param string $description Description text
     *
     * @return self
     */
    public function description(string $description = ''): self;

    /**
     * Make the post type public
     *
     * @param bool $public Whether the post type is public
     *
     * @return self
     */
    public function public(bool $public = true): self;

    /**
     * Set whether the post type is publicly queryable
     *
     * @param bool $queryable Whether publicly queryable
     *
     * @return self
     */
    public function publiclyQueryable(bool $queryable = 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;

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

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

    /**
     * Set capability type
     *
     * @param string $type Capability type (e.g., 'post', 'page')
     *
     * @return self
     */
    public function capabilityType(string $type = 'post'): self;

    /**
     * Enable/disable archive page
     *
     * @param bool $hasArchive Whether to have archive
     *
     * @return self
     */
    public function hasArchive(bool $hasArchive = true): self;

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

    /**
     * Set menu position
     *
     * @param int|null $position Menu position (5, 10, 15, etc.)
     *
     * @return self
     */
    public function menuPosition(?int $position = null): self;

    /**
     * Set menu icon
     *
     * @param string $icon Dashicon name or URL
     *
     * @return self
     */
    public function menuIcon(string $icon = ''): self;

    /**
     * Configure supported features
     *
     * @param array $supports Array of features (title, editor, thumbnail, etc.)
     *
     * @return self
     */
    public function supports(array $supports): self;

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

    /**
     * Register taxonomies for this post type
     *
     * @param array $taxonomies Array of taxonomy slugs
     *
     * @return self
     */
    public function taxonomies(array $taxonomies): self;

    /**
     * Add custom meta box callback
     *
     * @param callable $callback Callback function for meta box
     *
     * @return self
     */
    public function withMetaBoxCallback(callable $callback): self;

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