<?php
/**
 * Contract for admin pages.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Admin;

/**
 * Contract for admin pages.
 *
 * Each admin page in Postlinkly is one class implementing this interface.
 * `AdminMenu` discovers and registers them; `AssetRegistrar` asks each
 * page which assets it needs; the page's `render()` method outputs the
 * HTML when WordPress calls the page callback.
 *
 * Implementations must be side-effect free at construction time. All
 * WordPress calls (add_menu_page, enqueue_script, etc.) happen through
 * the hook system, not in constructors.
 *
 * @since 1.0.0
 */
interface AdminPage {

	/**
	 * Returns the unique page slug.
	 *
	 * Used as the `$menu_slug` argument to `add_menu_page` /
	 * `add_submenu_page`. Must be prefixed `postlinkly`.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_slug(): string;

	/**
	 * Returns the capability required to access this page.
	 *
	 * Should delegate to {@see \Postlinkly\Capabilities\CapabilityMap::for()}.
	 *
	 * @since 1.0.0
	 *
	 * @return string WordPress capability string.
	 */
	public function get_capability(): string;

	/**
	 * Returns the menu title (short, shown in the sidebar).
	 *
	 * @since 1.0.0
	 *
	 * @return string Translated string.
	 */
	public function get_menu_title(): string;

	/**
	 * Returns the page title (shown in the browser tab and page heading).
	 *
	 * @since 1.0.0
	 *
	 * @return string Translated string.
	 */
	public function get_page_title(): string;

	/**
	 * Returns the asset handles this page requires.
	 *
	 * `AssetRegistrar` calls this to decide which scripts and styles to
	 * enqueue when the page is active. Return an empty array when the
	 * page uses only the shared admin bundle.
	 *
	 * @since 1.0.0
	 *
	 * @return array<int, string> Asset handle strings.
	 */
	public function get_required_assets(): array;

	/**
	 * Outputs the page HTML.
	 *
	 * Called by WordPress as the `$callback` argument to
	 * `add_menu_page` / `add_submenu_page`. Must escape all output.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	public function render(): void;
}