<?php
/**
 * Contract every BW Dev module implements. The core (BW_Dev_Plugin) holds a
 * registry of these and conditionally calls register() based on the user's
 * Modules tab toggles.
 *
 * @package BW_Dev
 */

defined( 'ABSPATH' ) || exit;

interface BW_Dev_Module_Interface {

	/**
	 * Stable internal slug. Used as the key under bw_dev_settings, the form
	 * field namespace, and the settings-page tab ID. PHP-style (underscores),
	 * matching the legacy options being migrated where possible.
	 */
	public function slug(): string;

	/**
	 * Human-readable label shown in the Modules tab and as the tab title.
	 * Must be translatable.
	 */
	public function label(): string;

	/**
	 * Group slug placing this module in the Settings → BW Dev sidebar. One of:
	 *   - 'core'         framework/system-level (Modules, Branding, Flywheel)
	 *   - 'editor_admin' admin/editor enhancements (SVG Upload, Admin Note, Sticky, Admin Columns)
	 *   - 'frontend'     visitor-facing behaviors (Favicon, Menu Visibility)
	 *   - 'security'     hardening + protection (Hide Login URL, Security Hardening, Login Activity Log)
	 *   - 'indexing'     crawlers + AI-readiness (Robots.txt Manager, LLMs.txt Generator)
	 *   - 'blocks'       Gutenberg blocks (YouTube, Post Link, Subtitle, Separator)
	 *   - 'vendors'      recommended third-party plugins (install/activate helpers)
	 * Unknown values fall back to 'core' in the admin page renderer.
	 */
	public function group(): string;

	/**
	 * Initial settings shape used when the module has no data yet.
	 */
	public function default_settings(): array;

	/**
	 * Sanitize a submitted form payload for this module. Receives the raw
	 * (unslashed) array from $_POST['bw_dev_settings'][<slug>]. Returns a
	 * normalized array safe to persist.
	 */
	public function sanitize( array $data ): array;

	/**
	 * Wire up all the module's hooks. Called by the core ONLY if the module
	 * is enabled in the Modules tab. A disabled module must register no
	 * hooks, enqueue no assets, and consume no request resources.
	 */
	public function register(): void;

	/**
	 * Render the body of this module's settings tab. The surrounding <form>
	 * and submit button are emitted by BW_Dev_Admin_Page. Field names should
	 * be in the namespace bw_dev_settings[<slug>][...].
	 */
	public function render_tab(): void;

	/**
	 * Per-module uninstall cleanup, called from uninstall.php in addition to
	 * the core dropping bw_dev_settings. For most modules this is a no-op
	 * (the root option drop covers persisted state).
	 */
	public function uninstall(): void;
}
