<?php

declare( strict_types=1 );

namespace StrykeWP\Modules;

use StrykeWP\Core\Logger;
use StrykeWP\Core\OptionManager;

/**
 * Contract for all STRYKE WP modules.
 *
 * Each module must:
 * - Declare a unique ID, human-readable name, description, and version.
 * - Provide a boot() method that registers WordPress hooks when called.
 * - Optionally handle activate/deactivate lifecycle events.
 *
 * @package StrykeWP\Modules
 */
interface ModuleInterface {

	/**
	 * Unique machine-readable identifier.
	 * Used as option key suffix and URL slug.
	 *
	 * @example 'connector', 'branding', 'backup', 'wip_mode'
	 */
	public function get_id(): string;

	/**
	 * Human-readable module name (translatable).
	 */
	public function get_name(): string;

	/**
	 * Short description of what the module does (translatable).
	 */
	public function get_description(): string;

	/**
	 * Module version string.
	 */
	public function get_version(): string;

	/**
	 * Dashicon class name for use in the module card UI.
	 *
	 * @example 'dashicons-admin-network', 'dashicons-art'
	 */
	public function get_icon(): string;

	/**
	 * Registers WordPress hooks.
	 *
	 * Called only when the module is enabled. Receives shared services
	 * so modules do not need to create their own service instances.
	 *
	 * @param Logger        $logger  Shared logging service.
	 * @param OptionManager $options Shared options service.
	 */
	public function boot( Logger $logger, OptionManager $options ): void;

	/**
	 * Runs when the module is first enabled via the dashboard.
	 * Use for one-time setup (e.g., creating DB tables, scheduling cron).
	 */
	public function on_enable(): void;

	/**
	 * Runs when the module is disabled via the dashboard.
	 * Use for cleanup (e.g., clearing scheduled cron, removing transients).
	 */
	public function on_disable(): void;

	/**
	 * Renders the module-specific settings content inside the STRYKE WP dashboard.
	 *
	 * Called by Dashboard::render_module_content() when the module is enabled.
	 * The no-op default in AbstractModule shows a generic "no settings" notice.
	 */
	public function render_settings(): void;
}
