<?php

namespace Limb_Chatbot\Includes\Widgets\Data;

use Limb_Chatbot\Includes\Data_Objects\Widget;

/**
 * Widget data validator/sanitizer contract.
 *
 * @since 2.0.0
 */
interface Widget_Config_Interface {

	/**
	 * Get normalized config payload.
	 *
	 * @return array
	 */
	public function get_config(): array;

	/**
	 * Set normalized config payload.
	 *
	 * @param  array  $config  Config payload.
	 *
	 * @return void
	 */
	public function set_config( array $config ): void;

	/**
	 * Return sanitized widget data payload.
	 *
	 * @param  mixed  $data  Raw payload.
	 *
	 * @return array
	 */
	public function sanitize( $data ): array;

	/**
	 * Validate sanitized payload.
	 *
	 * @param  mixed  $data  Sanitized payload.
	 *
	 * @return bool
	 */
	public function validate( $data ): bool;

	/**
	 * Field-keyed validation messages for sanitized config (keys are relative to `config`, e.g. `prompt`, `click_behavior`).
	 *
	 * @param  mixed  $data  Sanitized payload.
	 *
	 * @return array<string, string> Empty when valid.
	 */
	public function get_validation_errors( $data ): array;

	public function get_dependencies();

	/**
	 * Return translatable config field descriptors.
	 *
	 * Descriptor shape:
	 * - path: dot path, supports `*` for list indices (e.g. `items.*.text`)
	 * - type: `string` or `rich_blocks`
	 *
	 * @return array<int,array{path:string,type:string}>
	 */
	public function get_translatable_fields(): array;
}
