<?php

namespace SugarCalendarBookings\Antispam\Captcha\Settings;

/**
 * Contract for a captcha category's settings UI block on the Anti-Spam tab.
 *
 * Each implementation owns one card on the methods grid and one panel below
 * it — card metadata, panel rendering, validation rules, post-data sanitize,
 * and the localized admin script data block.
 *
 * Adding a captcha category = one new implementation + one entry in the
 * registry's settings map.
 *
 * @since 1.5.0
 */
interface CaptchaSettingsInterface {

	/**
	 * Stable key matching the verifier `CATEGORY` constant. Also used for the
	 * DOM `data-method` attribute and the `#scb-antispam-panel-{key}` id.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function get_key(): string;

	/**
	 * Card metadata for the methods-selection grid.
	 *
	 * Shape: [ 'title' => string, 'icon' => string, 'description' => string ].
	 *
	 * @since 1.5.0
	 *
	 * @return array
	 */
	public function get_card(): array;

	/**
	 * Default flat method-key written when this category is freshly selected.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function default_method_key(): string;

	/**
	 * Flat method-keys owned by this category.
	 *
	 * Derived by iterating the verifier registry and matching `::CATEGORY`.
	 *
	 * @since 1.5.0
	 *
	 * @return array<int, string>
	 */
	public function get_method_keys(): array;

	/**
	 * Whether the given stored method-key belongs to this category.
	 *
	 * @since 1.5.0
	 *
	 * @param string $method Stored flat method-key.
	 *
	 * @return bool
	 */
	public function owns_method( string $method ): bool;

	/**
	 * Render the panel HTML for this category.
	 *
	 * Echoes captured `UI::*` output via the form wrapper assembled by the tab.
	 *
	 * @since 1.5.0
	 *
	 * @param string $stored_method Currently saved flat method-key.
	 *
	 * @return string
	 */
	public function render_panel( string $stored_method ): string;

	/**
	 * Validation rules contributed to `get_post_data_processing_rules()`.
	 *
	 * Keys are dotted option paths under `antispam.{key}.*`.
	 *
	 * @since 1.5.0
	 *
	 * @return array<string, string>
	 */
	public function get_validation_rules(): array;

	/**
	 * Sanitize the submitted `antispam` slice owned by this category.
	 *
	 * Typical responsibilities: drop transient form inputs that aren't
	 * stored; strip secret values when the resolved secret is filter-
	 * overridden so the override doesn't get persisted into the DB.
	 *
	 * @since 1.5.0
	 *
	 * @param array $antispam Submitted `antispam` array slice.
	 *
	 * @return array Mutated array slice.
	 */
	public function sanitize_post_data( array $antispam ): array;

	/**
	 * Localized JS data block contributed under
	 * `sugar_calendar_bookings_admin.antispam[key]`.
	 *
	 * @since 1.5.0
	 *
	 * @return array
	 */
	public function get_admin_script_data(): array;

	/**
	 * User-facing description shown under the preview widget when this
	 * category is active and keys are complete.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function get_preview_description(): string;
}
