<?php
/**
 * Form field utilities and helpers
 *
 * Provides helper methods for working with form fields, field definitions,
 * and field types.
 *
 * @package BW_Schema
 * @since 3.0.0-babel
 */

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

class BW_Schema_Form_Fields {

	/**
	 * Get all available field types
	 *
	 * @return array Field types with descriptions
	 */
	public static function get_field_types() {
		return array(
			'text'           => __( 'Text Input', 'bw-schema' ),
			'email'          => __( 'Email Input', 'bw-schema' ),
			'url'            => __( 'URL Input', 'bw-schema' ),
			'tel'            => __( 'Phone Number', 'bw-schema' ),
			'number'         => __( 'Number Input', 'bw-schema' ),
			'date'           => __( 'Date Picker', 'bw-schema' ),
			'time'           => __( 'Time Picker', 'bw-schema' ),
			'datetime-local' => __( 'DateTime Picker', 'bw-schema' ),
			'textarea'       => __( 'Textarea', 'bw-schema' ),
			'select'         => __( 'Dropdown Select', 'bw-schema' ),
			'radio'          => __( 'Radio Buttons', 'bw-schema' ),
			'checkbox'       => __( 'Single Checkbox', 'bw-schema' ),
			'checkboxes'     => __( 'Multiple Checkboxes', 'bw-schema' ),
		);
	}

	/**
	 * Get all available validation rules
	 *
	 * @return array Rules with descriptions
	 */
	public static function get_validation_rules() {
		return array(
			'required'     => __( 'Field is required', 'bw-schema' ),
			'email'        => __( 'Must be valid email', 'bw-schema' ),
			'url'          => __( 'Must be valid URL', 'bw-schema' ),
			'phone'        => __( 'Must be valid phone', 'bw-schema' ),
			'number'       => __( 'Must be number', 'bw-schema' ),
			'integer'      => __( 'Must be integer', 'bw-schema' ),
			'min_length:N' => __( 'Minimum N characters', 'bw-schema' ),
			'max_length:N' => __( 'Maximum N characters', 'bw-schema' ),
			'pattern:regex' => __( 'Must match regex', 'bw-schema' ),
		);
	}

	/**
	 * Get sanitization functions
	 *
	 * @return array Available sanitization functions
	 */
	public static function get_sanitize_functions() {
		return array(
			'sanitize_text_field'       => __( 'Text Field', 'bw-schema' ),
			'sanitize_email'            => __( 'Email Address', 'bw-schema' ),
			'sanitize_key'              => __( 'Slug/Key', 'bw-schema' ),
			'sanitize_textarea_field'   => __( 'Textarea (HTML allowed)', 'bw-schema' ),
			'wp_kses_post'              => __( 'Post HTML', 'bw-schema' ),
			'intval'                    => __( 'Integer', 'bw-schema' ),
			'floatval'                  => __( 'Float', 'bw-schema' ),
			'absint'                    => __( 'Absolute Integer', 'bw-schema' ),
			'esc_url_raw'               => __( 'URL (raw)', 'bw-schema' ),
		);
	}

	/**
	 * Create a text field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional field arguments
	 * @return array Field definition
	 */
	public static function text( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'text',
			'sanitize' => 'sanitize_text_field',
		));
	}

	/**
	 * Create an email field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function email( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'email',
			'validate' => array( 'email' ),
			'sanitize' => 'sanitize_email',
		));
	}

	/**
	 * Create a URL field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function url( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'url',
			'validate' => array( 'url' ),
			'sanitize' => 'esc_url_raw',
		));
	}

	/**
	 * Create a phone field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function phone( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'tel',
			'validate' => array( 'phone' ),
			'sanitize' => 'sanitize_text_field',
		));
	}

	/**
	 * Create a number field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function number( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'number',
			'validate' => array( 'number' ),
			'sanitize' => 'floatval',
		));
	}

	/**
	 * Create a textarea field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function textarea( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'textarea',
			'rows'     => 5,
			'sanitize' => 'wp_kses_post',
		));
	}

	/**
	 * Create a select field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $options Options (key => label)
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function select( $name, $label, $options = array(), $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'select',
			'options'  => $options,
			'sanitize' => 'sanitize_key',
		));
	}

	/**
	 * Create a radio field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $options Options (key => label)
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function radio( $name, $label, $options = array(), $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'radio',
			'options'  => $options,
			'sanitize' => 'sanitize_key',
		));
	}

	/**
	 * Create a checkbox field definition (single)
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function checkbox( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'checkbox',
			'sanitize' => function( $value ) {
				return $value ? 1 : 0;
			},
		));
	}

	/**
	 * Create multiple checkboxes field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $options Options (key => label)
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function checkboxes( $name, $label, $options = array(), $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'checkboxes',
			'options'  => $options,
			'sanitize' => function( $values ) {
				return is_array( $values ) ? array_map( 'sanitize_text_field', $values ) : array();
			},
		));
	}

	/**
	 * Create a date field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function date( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'date',
			'sanitize' => 'sanitize_text_field',
		));
	}

	/**
	 * Create a time field definition
	 *
	 * @param string $name Field name
	 * @param string $label Field label
	 * @param array  $args Additional arguments
	 * @return array Field definition
	 */
	public static function time( $name, $label, $args = array() ) {
		return wp_parse_args( $args, array(
			'name'     => $name,
			'label'    => $label,
			'type'     => 'time',
			'sanitize' => 'sanitize_text_field',
		));
	}

	/**
	 * Add common field properties
	 *
	 * Utility for adding required, help text, etc. to any field.
	 *
	 * @param array $field Field definition
	 * @param array $props Properties to add
	 * @return array Modified field definition
	 */
	public static function add_props( $field, $props ) {
		return array_merge( $field, $props );
	}

	/**
	 * Make a field required
	 *
	 * @param array $field Field definition
	 * @return array Field with required=true
	 */
	public static function required( $field ) {
		$field['required'] = true;
		if ( ! isset( $field['validate'] ) ) {
			$field['validate'] = array();
		}
		if ( ! is_array( $field['validate'] ) ) {
			$field['validate'] = array( $field['validate'] );
		}
		if ( ! in_array( 'required', $field['validate'], true ) ) {
			array_unshift( $field['validate'], 'required' );
		}
		return $field;
	}

	/**
	 * Add help text to a field
	 *
	 * @param array  $field Field definition
	 * @param string $help Help text
	 * @return array Field with help text
	 */
	public static function help( $field, $help ) {
		$field['help'] = $help;
		return $field;
	}

	/**
	 * Add placeholder to a field
	 *
	 * @param array  $field Field definition
	 * @param string $placeholder Placeholder text
	 * @return array Field with placeholder
	 */
	public static function placeholder( $field, $placeholder ) {
		$field['placeholder'] = $placeholder;
		return $field;
	}

	/**
	 * Add validation rule to a field
	 *
	 * @param array        $field Field definition
	 * @param string|callable $rule Validation rule
	 * @return array Field with validation
	 */
	public static function validate( $field, $rule ) {
		if ( ! isset( $field['validate'] ) ) {
			$field['validate'] = array();
		}
		if ( ! is_array( $field['validate'] ) ) {
			$field['validate'] = array( $field['validate'] );
		}
		$field['validate'][] = $rule;
		return $field;
	}

	/**
	 * Group fields by section
	 *
	 * Organizes fields into sections for display.
	 *
	 * @param array $fields Array of field definitions
	 * @return array Fields grouped by section name
	 */
	public static function group_by_section( $fields ) {
		$grouped = array();

		foreach ( $fields as $field ) {
			$section = $field['section'] ?? 'general';
			if ( ! isset( $grouped[ $section ] ) ) {
				$grouped[ $section ] = array();
			}
			$grouped[ $section ][] = $field;
		}

		return $grouped;
	}

	/**
	 * Filter fields by section
	 *
	 * @param array  $fields Array of field definitions
	 * @param string $section Section name
	 * @return array Fields in that section only
	 */
	public static function filter_by_section( $fields, $section ) {
		return array_filter( $fields, function( $field ) use ( $section ) {
			return ( $field['section'] ?? 'general' ) === $section;
		});
	}

	/**
	 * Filter fields by type
	 *
	 * @param array  $fields Array of field definitions
	 * @param string $type Field type
	 * @return array Fields of that type only
	 */
	public static function filter_by_type( $fields, $type ) {
		return array_filter( $fields, function( $field ) use ( $type ) {
			return ( $field['type'] ?? 'text' ) === $type;
		});
	}
}