<?php
/**
 * Contract every MenuVerse module implements.
 *
 * @package MenuVerse
 */

namespace WPXero\MenuVerse\Modules;

defined( 'ABSPATH' ) || exit;

/**
 * A module is a self contained navigation feature that can be toggled off
 * without leaving any code path behind on the frontend.
 */
interface Module {

	/**
	 * Returns the module identifier used in settings, REST routes and hooks.
	 *
	 * @return string
	 */
	public static function id();

	/**
	 * Returns the translated module label.
	 *
	 * @return string
	 */
	public static function label();

	/**
	 * Returns the translated one line module description.
	 *
	 * @return string
	 */
	public static function description();

	/**
	 * Returns the settings schema for the module.
	 *
	 * Must be free of side effects: it is called for disabled modules too so
	 * the dashboard can render their settings panel.
	 *
	 * @return array
	 */
	public static function schema();

	/**
	 * Registers hooks. Called only when the module is enabled.
	 *
	 * @return void
	 */
	public function boot();

	/**
	 * Registers, but never enqueues, the module's frontend assets.
	 *
	 * @return void
	 */
	public function register_assets();

	/**
	 * Renders the module markup.
	 *
	 * Never called directly from a render path. `output()` is the entry point;
	 * this is the part of it a module writes.
	 *
	 * @param array $settings Resolved settings for this render.
	 * @param array $context  Render context, including the calling `source`.
	 * @return string
	 */
	public function render( array $settings, array $context );

	/**
	 * Runs the full render pipeline and returns the markup.
	 *
	 * Every render path — block, shortcode, template tag, automatic
	 * placement, preview — goes through here, which is what makes the
	 * extension hooks and the conditional asset loading unconditional.
	 * `Abstract_Module` implements it; a module that implements this
	 * interface directly has to supply the pipeline itself.
	 *
	 * @param array $args    Per call settings overriding stored values.
	 * @param array $context Render context, including the calling `source`.
	 * @return string
	 */
	public function output( array $args = array(), array $context = array() );
}
