<?php
/**
 * One part of the review form.
 *
 * @package WPInterface\ProductReviews
 */

declare( strict_types=1 );

namespace WPInterface\ProductReviews\Collection\Form;

defined( 'ABSPATH' ) || exit;

/**
 * A field renders its inputs, turns submitted input into a clean value, and stores that value
 * on the review. The same field serves the REST endpoint and the classic comment form post.
 */
interface FormField {

	/**
	 * Before the name and email fields (rating, text, photos…).
	 */
	public const AREA_MAIN = 'main';

	/**
	 * After the name and email fields, before the submit button (display name, consent…).
	 */
	public const AREA_AFTER = 'after';

	/**
	 * Field id, also the key of its value in a ReviewDraft.
	 */
	public function id(): string;

	/**
	 * Sort order within the area.
	 */
	public function position(): int;

	/**
	 * Where the field is shown: AREA_MAIN or AREA_AFTER.
	 */
	public function area(): string;

	/**
	 * Whether the field is used for this product and visitor.
	 *
	 * @param FormContext $context Form context.
	 */
	public function applies( FormContext $context ): bool;

	/**
	 * Field HTML.
	 *
	 * @param FormContext $context Form context.
	 */
	public function render( FormContext $context ): string;

	/**
	 * Clean value from submitted input.
	 *
	 * @param array<string, mixed> $input   Unslashed request parameters.
	 * @param FormContext          $context Form context.
	 * @return mixed|\WP_Error Value, null when left empty, or an error whose data names the input.
	 */
	public function parse( array $input, FormContext $context );

	/**
	 * Store a parsed value on a review.
	 *
	 * @param int         $comment_id Review id.
	 * @param mixed       $value      Parsed value.
	 * @param FormContext $context    Form context.
	 */
	public function save( int $comment_id, $value, FormContext $context ): void;

	/**
	 * Stored value, to pre-fill the form when a reviewer edits a review.
	 *
	 * @param int $comment_id Review id.
	 * @return mixed
	 */
	public function load( int $comment_id );
}