<?php
/**
 * The Feature contract.
 *
 * @package Adminkeep
 */

namespace Adminkeep;

defined( 'ABSPATH' ) || exit;

/**
 * A self-contained unit of behaviour.
 *
 * A feature depends on nothing but the settings array it is handed. It must register zero hooks
 * until boot() is called, and boot() is only called when the feature is enabled — that is the
 * plugin's performance guarantee and it is asserted by test.
 */
interface Feature {

	/**
	 * Stable identifier, used as the settings key. Snake case.
	 *
	 * @return string
	 */
	public function id();

	/**
	 * Human-readable name for the settings screen.
	 *
	 * @return string
	 */
	public function label();

	/**
	 * One-sentence description for the settings screen.
	 *
	 * @return string
	 */
	public function description();

	/**
	 * Settings schema: field key => array( 'type', 'default', 'ui' ).
	 *
	 * 'enabled' is handled by the registry and must not appear here.
	 *
	 * **This runs on `plugins_loaded`, before `init`, so it must contain no translated
	 * strings.** Calling __() here triggers WordPress's "translation loading was triggered too
	 * early" notice. Field labels live in field_label() instead, which only runs at render time.
	 *
	 * @return array
	 */
	public function settings_schema();

	/**
	 * Human-readable label for a settings field.
	 *
	 * Called only when rendering the settings screen, which is safely after init — this is
	 * where translated strings for fields belong.
	 *
	 * @param string $key Field key.
	 * @return string
	 */
	public function field_label( $key );

	/**
	 * Register hooks. Called only when the feature is enabled.
	 *
	 * @param array $settings Resolved settings for this feature.
	 * @return void
	 */
	public function boot( array $settings );
}