<?php

namespace Storeplugin\PDFInvoice\Framework\Contracts;

defined('ABSPATH') || exit;

/**
 * Settings Panel Builder Interface
 *
 * Defines the public API for creating and configuring settings panels.
 * This interface exposes only the methods that should be used by developers
 * to build settings pages. Internal WordPress callback methods are marked
 * with @internal in the implementing class and should not be called directly.
 *
 * @package Storeplugin\PDFInvoice\Framework\Contracts
 */
interface SettingInterface
{
    /**
     * Create a new settings panel instance
     *
     * @param string $pageTitle   Page title displayed in browser
     * @param string $menuTitle   Menu title displayed in admin sidebar
     * @param string $slug        Unique menu slug identifier
     * @param string $optionName  Option key used for storing panel values
     * @param string $capability  Required user capability (default: 'manage_options')
     * @param string $icon        Dashicon class name (default: 'dashicons-admin-generic')
     * @param int    $position    Menu position (default: 2)
     *
     * @return self
     */
    public static function create(
        string $pageTitle,
        string $menuTitle,
        string $slug,
        string $optionName,
        string $capability = 'manage_options',
        string $icon = 'dashicons-admin-generic',
        int $position = 2
    ): self;

    /**
     * Add a tab to the settings panel
     *
     * Creates a navigation tab with sublinks. Tabs organize settings into
     * logical groups with expandable submenus.
     *
     * @param string         $id       Unique tab identifier
     * @param string         $title    Display title for the tab
     * @param string         $icon     Dashicon slug (without 'dashicons-' prefix)
     * @param array|callable $sublinks Array of sublinks or callback function receiving Tab instance
     *
     * @return self
     */
    public function addTab(string $id, string $title, string $icon, $sublinks = []): self;

    /**
     * Set the title for the next group
     *
     * @param string $title Group title
     *
     * @return self
     */
    public function withGroupTitle(string $title): self;

    /**
     * Set the description for the next group
     *
     * @param string $description Group description
     *
     * @return self
     */
    public function withGroupDescription(string $description): self;

    /**
     * Add a group directly without tab navigation
     *
     * For simple settings pages that don't need tabs, this creates a
     * standalone group with fields. Use withGroupTitle() and
     * withGroupDescription() to set the group metadata before calling this.
     *
     * @param array|callable $config Group configuration array or callback function
     *
     * @return self
     */
    public function addGroup($config = []): self;

    /**
     * Register as a top-level admin menu
     *
     * Creates a new top-level menu item in the WordPress admin sidebar
     * with its own icon and position.
     *
     * @return self
     */
    public function withAdminMenu(): self;

    /**
     * Register as a submenu under a parent menu
     *
     * Adds this settings page as a submenu item under an existing menu.
     * Common parent slugs: 'options-general.php', 'tools.php', etc.
     *
     * @param string $parentSlug Parent menu slug
     *
     * @return self
     */
    public function withAdminSubmenu(string $parentSlug): self;

    /**
     * Register as a submenu under a post type menu
     *
     * Adds this settings page under a custom post type's admin menu.
     *
     * @param string $postType Post type slug
     *
     * @return self
     */
    public function withAdminSubmenuPostType(string $postType): self;

    /**
     * Add a sidebar callback for additional content
     *
     * Provides a callback function to render content in a sidebar column
     * (typically used for advertisements, tips, or help content).
     *
     * @param callable $callback Function to render sidebar content
     *
     * @return self
     */
    public function withSidebarCallback(callable $callback): self;

    /**
     * Register and initialize the settings panel
     *
     * This finalizes the panel configuration and registers it with WordPress.
     * Must be called as the last method in the chain.
     *
     * @return void
     */
    public function render(): void;

    /**
     * Check if a slug belongs to a registered settings panel
     *
     * @param string $slug Panel slug to check
     *
     * @return bool
     */
    public static function isRegisteredSlug(string $slug): bool;

    /**
     * Check if an option key belongs to a registered settings panel.
     *
     * @param string $optionName Option key to check.
     *
     * @return bool
     */
    public static function isRegisteredOptionName(string $optionName): bool;

    /**
     * Get registered settings option keys for this request.
     *
     * @return array<int, string>
     */
    public static function getRegisteredOptionNames(): array;

    /**
     * Check if the panel has tabs configured
     *
     * @return bool
     */
    public function hasTabs(): bool;
}
