<?php
/**
 * What every form plugin has to offer this one.
 *
 * @package TextTango
 */

declare( strict_types=1 );

namespace TextTango\Forms;

defined( 'ABSPATH' ) || exit;

/**
 * The contract a form plugin adapter fulfils (spec §21).
 *
 * Deliberately small. Each adapter answers four questions — is your plugin
 * here, what forms exist, what fields does one have, and tell me when somebody
 * submits — and everything after that is shared. Anything larger would push the
 * differences between four form plugins into the code that sends messages,
 * which is where they would do the most harm.
 */
interface Provider {

	/**
	 * A short, stable identifier, used in settings keys.
	 *
	 * Never change one of these: it is half of the key a merchant's per-form
	 * configuration is stored under, so renaming it silently unconfigures every
	 * form they had set up.
	 */
	public static function slug(): string;

	/**
	 * The plugin's name, as the merchant knows it.
	 */
	public static function label(): string;

	/**
	 * Whether the plugin is installed and active.
	 *
	 * Checked by a function or class the plugin defines, never by a path or an
	 * option — the same test {@see \TextTango\WooCommerce\Notifications::woocommerce_active()}
	 * makes, and for the same reason: a plugin's files can be present while it is
	 * deactivated.
	 */
	public static function is_active(): bool;

	/**
	 * Every form this plugin holds, as id => title.
	 *
	 * @return array<string, string>
	 */
	public static function forms(): array;

	/**
	 * The field names on one form.
	 *
	 * Used to build the mapping controls, so a merchant chooses from a list
	 * rather than typing a field name and hoping. Returns an empty array when the
	 * form cannot be read, which the settings screen renders as a plain text box
	 * so the feature is still usable.
	 *
	 * @param string $form_id Form id.
	 * @return string[]
	 */
	public static function fields( string $form_id ): array;

	/**
	 * Hook this plugin's submission event.
	 *
	 * The adapter's whole job at runtime: catch a submission, normalise it into a
	 * {@see Submission}, and hand it to {@see Forms::handle()}.
	 */
	public function register(): void;
}
