<?php
/**
 * Abstract base class for content blocks.
 *
 * @package Wlconduit
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Base class every content block must extend.
 *
 * Defines the contract for block definitions (admin UI),
 * input schema generation (MCP tools/list), and execution (MCP tools/call).
 *
 * @since 1.0.0
 */
abstract class Wlconduit_Block_Base {

	/**
	 * Human-readable label for the admin UI palette.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	abstract public function get_label(): string;

	/**
	 * Dashicon name for the admin UI palette.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	abstract public function get_icon(): string;

	/**
	 * Available native fields the admin can toggle on/off.
	 *
	 * Returns an associative array of field_key => field_label.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, string>
	 */
	abstract public function get_available_fields(): array;

	/**
	 * Available filters the admin can enable as LLM input parameters.
	 *
	 * Returns an associative array of filter_key => filter_schema.
	 * Each filter_schema contains 'type', 'description', and optionally
	 * 'default', 'enum', etc.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, array>
	 */
	abstract public function get_available_filters(): array;

	/**
	 * Execute the block query and return data.
	 *
	 * @since 1.0.0
	 *
	 * @param array $config    The block's saved configuration.
	 * @param array $arguments The LLM-provided input arguments.
	 * @return array The query results.
	 */
	abstract public function execute( array $config, array $arguments ): array;

	/**
	 * Map admin-friendly field keys to actual database column names.
	 *
	 * Used by the query builder to translate field keys stored in tool
	 * configs (e.g., 'title') into SQL column names (e.g., 'post_title')
	 * for SELECT and ORDER BY clauses in joined queries.
	 *
	 * Each block defines its own mapping. Add-on blocks with custom tables
	 * must override this to map their field keys to their table's columns.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, string> Field key => database column name.
	 */
	public function get_field_column_map(): array {
		return array();
	}

	/**
	 * Get joinable column information for this block type.
	 *
	 * Returns the database table name, meta table name, ID column,
	 * and available native columns that can be used in joins.
	 *
	 * @since 1.0.0
	 *
	 * @return array {
	 *     @type array  $native         Associative array of column_name => label.
	 *     @type string $table          The full database table name.
	 *     @type string $meta_table     The full meta table name, or empty if none.
	 *     @type string $meta_fk_column The foreign key column in the meta table that references this table's ID.
	 *     @type string $id_column      The primary key column name.
	 * }
	 */
	public function get_joinable_columns(): array {
		return array(
			'native'         => array(),
			'table'          => '',
			'meta_table'     => '',
			'meta_fk_column' => '',
			'id_column'      => '',
		);
	}

	/**
	 * Build inputSchema properties from the block's enabled filters.
	 *
	 * Reads the saved config to determine which filters are enabled
	 * and generates JSON Schema properties for the MCP tool definition.
	 *
	 * @since 1.0.0
	 *
	 * @param array $config The block's saved configuration.
	 * @return array<string, array> JSON Schema properties.
	 */
	public function get_input_schema_properties( array $config ): array {
		$properties = array();
		$available  = $this->get_available_filters();

		foreach ( $config['filters'] ?? array() as $key => $filter_config ) {
			if ( empty( $filter_config['enabled'] ) ) {
				continue;
			}

			if ( ! isset( $available[ $key ] ) ) {
				continue;
			}

			$prop = $available[ $key ];

			if ( ! empty( $filter_config['description'] ) ) {
				$prop['description'] = $filter_config['description'];
			}

			$properties[ $key ] = $prop;
		}

		return $properties;
	}

	/**
	 * Full definition for the admin UI.
	 *
	 * Combines label, icon, available fields, and available filters
	 * into a single array the React app can consume.
	 *
	 * @since 1.0.0
	 *
	 * @return array
	 */
	/**
	 * Validate a date string is in YYYY-MM-DD format.
	 *
	 * @since 1.0.0
	 *
	 * @param string $date The date string to validate.
	 * @return bool True if valid YYYY-MM-DD format.
	 */
	protected function is_valid_date( string $date ): bool {
		return (bool) preg_match( '/^\d{4}-\d{2}-\d{2}$/', $date );
	}

	/**
	 * Full definition for the admin UI.
	 *
	 * Combines label, icon, available fields, and available filters
	 * into a single array the React app can consume.
	 *
	 * @since 1.0.0
	 *
	 * @return array
	 */
	public function get_definition(): array {
		return array(
			'label'   => $this->get_label(),
			'icon'    => $this->get_icon(),
			'fields'  => $this->get_available_fields(),
			'filters' => $this->get_available_filters(),
		);
	}
}