<?php
/**
 * @package Hafenstudios\Leadlotse
 */

namespace Hafenstudios\Leadlotse\Fields;

defined( 'ABSPATH' ) || exit;

/**
 * Vertrag fuer einen Feldtyp: Sanitizing, Validierung und Render-Daten.
 *
 * Validierungsfehler werden als uebersetzter String zurueckgegeben (null = ok),
 * damit Fehlermeldungen immer Ursache und naechsten Schritt nennen koennen.
 */
interface FieldType {

	/**
	 * Eindeutiger Typ-Schluessel, z.B. "email".
	 *
	 * @return string
	 */
	public function key(): string;

	/**
	 * Bereinigt den eingereichten Rohwert.
	 *
	 * @param mixed                $value Rohwert aus dem Request.
	 * @param array<string, mixed> $field Felddefinition.
	 * @return mixed Bereinigter Wert.
	 */
	public function sanitize( $value, array $field );

	/**
	 * Validiert den bereinigten Wert.
	 *
	 * @param mixed                $value Bereinigter Wert.
	 * @param array<string, mixed> $field Felddefinition.
	 * @return string|null Fehlermeldung oder null bei Erfolg.
	 */
	public function validate( $value, array $field ): ?string;

	/**
	 * Liefert die Render-Daten fuer das Frontend (Etappe 3 nutzt sie im Builder
	 * und Frontend-Renderer).
	 *
	 * @param array<string, mixed> $field Felddefinition.
	 * @return array<string, mixed>
	 */
	public function render_data( array $field ): array;
}
