<?php

namespace WPForms\Integrations\Abilities;

use Closure;

/**
 * Curated field-type and property registry for the Abilities API writers.
 *
 * Two levels: a property catalog (defined once) and a type -> property-keys map.
 * Both are filterable so addons can extend without core edits.
 *
 * @since 1.10.2
 */
class FieldRegistry {

	/**
	 * Availability requirement: always available.
	 *
	 * @since 1.10.2
	 */
	private const ALWAYS = 'always';

	/**
	 * Availability requirement: requires Pro license.
	 *
	 * @since 1.10.2
	 */
	private const PRO = 'pro';

	/**
	 * Property catalog: key => [ schema fragment, sanitizer callable ].
	 *
	 * @since 1.10.2
	 *
	 * @return array
	 */
	private function properties(): array {

		$properties = [
			'label'           => [
				'schema'   => [ 'type' => 'string' ],
				'sanitize' => 'sanitize_text_field',
			],
			'description'     => [
				'schema'   => [ 'type' => 'string' ],
				'sanitize' => 'sanitize_text_field',
			],
			'required'        => [
				'schema'   => [ 'type' => 'boolean' ],
				'sanitize' => [ $this, 'sanitize_bool' ],
			],
			'size'            => [
				'schema'   => [
					'type' => 'string',
					'enum' => [ 'small', 'medium', 'large' ],
				],
				'sanitize' => 'sanitize_text_field',
			],
			'label_hide'      => [
				'schema'   => [ 'type' => 'boolean' ],
				'sanitize' => [ $this, 'sanitize_bool' ],
			],
			'placeholder'     => [
				'schema'   => [ 'type' => 'string' ],
				'sanitize' => 'sanitize_text_field',
			],
			'default_value'   => [
				'schema'   => [ 'type' => 'string' ],
				'sanitize' => 'sanitize_text_field',
			],
			'input_columns'   => [
				'schema'   => [
					'type' => 'string',
					'enum' => [ '', 'inline', '2', '3' ],
				],
				'sanitize' => 'sanitize_text_field',
			],
			'style'           => [
				// Shared `$field['style']` storage key. For Dropdown (select): `classic` is
				// the plain browser-native `<select>`, `modern` swaps in Choices.js. For
				// File Upload: `classic` is a single-file native input, `modern` is the
				// drag-and-drop multi-file uploader. Constants live on
				// WPForms_Field_Select::STYLE_{CLASSIC|MODERN} and Forms\Fields\FileUpload\Field::STYLE_{CLASSIC|MODERN}.
				'schema'   => [
					'type' => 'string',
					'enum' => [ 'classic', 'modern' ],
				],
				'sanitize' => 'sanitize_text_field',
			],
			'extensions'      => [
				// Comma-separated list of allowed file extensions, e.g. `"pdf,doc,docx,png,jpg"`.
				// WPForms itself enforces this at submit time; we just store it.
				'schema'   => [ 'type' => 'string' ],
				'sanitize' => 'sanitize_text_field',
			],
			'max_size'        => [
				// Per-file maximum size in megabytes. WPForms also caps it at `wp_max_upload_size()`
				// at submit time, so values above the server limit silently fall back to the cap.
				'schema'   => [
					'type'    => 'integer',
					'minimum' => 1,
				],
				'sanitize' => 'absint',
			],
			'max_file_number' => [
				// Maximum number of files a user can upload through the field. Applies only to
				// the modern (multi-file) uploader; the classic style is single-file.
				'schema'   => [
					'type'    => 'integer',
					'minimum' => 1,
				],
				'sanitize' => 'absint',
			],
			'media_library'   => [
				// Store uploads in the WordPress Media Library in addition to the form's
				// uploads directory. Maps to `$field['media_library']` ("1" / "").
				'schema'   => [ 'type' => 'boolean' ],
				'sanitize' => [ $this, 'sanitize_bool' ],
			],
			'choices'         => [
				'schema'   => [
					'type'  => 'array',
					'items' => [
						'type'                 => 'object',
						'properties'           => [
							'label' => [ 'type' => 'string' ],
							'value' => [ 'type' => 'string' ],
						],
						'required'             => [ 'label' ],
						'additionalProperties' => false,
					],
				],
				'sanitize' => [ $this, 'sanitize_choices' ],
			],
		];

		/**
		 * Filters the Abilities API field-property catalog.
		 *
		 * @since 1.10.2
		 *
		 * @param array $properties Property catalog.
		 */
		return (array) apply_filters( 'wpforms_integrations_abilities_field_registry_properties', $properties );
	}

	/**
	 * Curated type registry.
	 *
	 * Per-type entry keys:
	 *   - `requires`        — availability gate: 'always' | 'pro' | callable | addon slug.
	 *   - `label`           — human-readable type label (i18n).
	 *   - `props`           — string[] of property keys allowed for this type (subset of properties()).
	 *   - `required_props`  — string[] of property keys that MUST be supplied; checked by preflight
	 *                         in FormMutator. Deliberately NOT named `required` so filter authors
	 *                         do not confuse it with the availability key `requires`.
	 *
	 * @since 1.10.2
	 *
	 * @return array
	 */
	private function types(): array {

		$text   = [ 'label', 'description', 'required', 'size', 'label_hide', 'placeholder', 'default_value' ];
		$choice = [ 'label', 'description', 'required', 'size', 'label_hide', 'choices' ];

		$types = [
			'text'        => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Single Line Text', 'wpforms-lite' ),
				'props'    => $text,
			],
			'textarea'    => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Paragraph Text', 'wpforms-lite' ),
				'props'    => $text,
			],
			'email'       => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Email', 'wpforms-lite' ),
				'props'    => $text,
			],
			'number'      => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Numbers', 'wpforms-lite' ),
				'props'    => $text,
			],
			'select'      => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Dropdown', 'wpforms-lite' ),
				'props'    => array_merge( $choice, [ 'style' ] ),
			],
			'radio'       => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Multiple Choice', 'wpforms-lite' ),
				'props'    => array_merge( $choice, [ 'input_columns' ] ),
			],
			'checkbox'    => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Checkboxes', 'wpforms-lite' ),
				'props'    => array_merge( $choice, [ 'input_columns' ] ),
			],
			'name'        => [
				'requires' => self::ALWAYS,
				'label'    => __( 'Name', 'wpforms-lite' ),
				'props'    => [ 'label', 'description', 'required', 'size', 'label_hide' ],
			],
			'phone'       => [
				'requires' => self::PRO,
				'label'    => __( 'Phone', 'wpforms-lite' ),
				'props'    => $text,
			],
			'date-time'   => [
				'requires' => self::PRO,
				'label'    => __( 'Date / Time', 'wpforms-lite' ),
				'props'    => [ 'label', 'description', 'required', 'size', 'label_hide' ],
			],
			'file-upload' => [
				'requires' => self::PRO,
				'label'    => __( 'File Upload', 'wpforms-lite' ),
				'props'    => [
					'label',
					'description',
					'required',
					'size',
					'label_hide',
					'extensions',
					'max_size',
					'max_file_number',
					'media_library',
					'style',
				],
			],
		];

		/**
		 * Filters the Abilities API curated field-type registry.
		 *
		 * @since 1.10.2
		 *
		 * @param array $types Type registry.
		 */
		return (array) apply_filters( 'wpforms_integrations_abilities_field_registry_types', $types );
	}

	/**
	 * Human-readable label for a field type.
	 *
	 * @since 1.10.2
	 *
	 * @param string $type Field type.
	 *
	 * @return string The type's display label, or the raw type if unknown.
	 */
	public function get_type_label( string $type ): string {

		$types = $this->types();

		return $types[ $type ]['label'] ?? $type;
	}

	/**
	 * Whether a field type may be created or edited in this install.
	 *
	 * @since 1.10.2
	 *
	 * @param string $type Field type.
	 *
	 * @return bool
	 */
	public function is_field_type_available( string $type ): bool {

		$types = $this->types();

		if ( ! isset( $types[ $type ] ) ) {
			return false;
		}

		$requires = $types[ $type ]['requires'];

		if ( $requires === self::ALWAYS ) {
			return true;
		}

		if ( $requires === self::PRO ) {
			return wpforms()->is_pro();
		}

		// Accept callables shaped as Closures or [ $obj, 'method' ] arrays; a plain data
		// array (a likely filter-author mistake) is rejected here instead of warning
		// inside call_user_func() and silently falling through to false.
		if ( ( $requires instanceof Closure || is_array( $requires ) ) && is_callable( $requires ) ) {
			return (bool) call_user_func( $requires );
		}

		if ( is_string( $requires ) ) {
			return $this->is_addon_active( $requires );
		}

		// Fail closed on unknown shapes.
		return false;
	}

	/**
	 * Whether the given WPForms addon plugin is active.
	 *
	 * Lazily loads wp-admin/includes/plugin.php so the function is available
	 * outside the admin context.
	 *
	 * @since 1.10.2
	 *
	 * @param string $slug Addon plugin slug (e.g. 'wpforms-signatures').
	 *
	 * @return bool
	 */
	private function is_addon_active( string $slug ): bool {

		if ( ! function_exists( 'is_plugin_active' ) ) {
			require_once ABSPATH . 'wp-admin/includes/plugin.php';
		}

		return is_plugin_active( "{$slug}/{$slug}.php" );
	}

	/**
	 * Required property keys for a field type.
	 *
	 * Reads the `required_props` list declared in the type's registry entry, or
	 * returns an empty array when none are declared. The key is intentionally NOT
	 * `required` so filter authors cannot confuse it with the availability key
	 * `requires` (one letter apart, completely different meaning).
	 *
	 * @since 1.10.2
	 *
	 * @param string $type Field type.
	 *
	 * @return string[]
	 */
	public function required_properties( string $type ): array {

		$types = $this->types();

		return $types[ $type ]['required_props'] ?? [];
	}

	/**
	 * Available type keys for this install.
	 *
	 * Filters the curated set by per-type availability (Pro / addon active / callable).
	 * Use for discovery output (describer, listings) so unavailable types are not advertised.
	 *
	 * @since 1.10.2
	 *
	 * @return string[]
	 */
	public function available_types(): array {

		return array_values(
			array_filter(
				array_keys( $this->types() ),
				[ $this, 'is_field_type_available' ]
			)
		);
	}

	/**
	 * Allowed property keys for a type.
	 *
	 * @since 1.10.2
	 *
	 * @param string $type Field type.
	 *
	 * @return string[]
	 */
	public function allowed_properties( string $type ): array {

		$types = $this->types();

		return $types[ $type ]['props'] ?? [];
	}

	/**
	 * Sanitize and filter incoming properties for a type.
	 *
	 * @since 1.10.2
	 *
	 * @param string $type  Field type.
	 * @param array  $input Raw property input.
	 *
	 * @return array Sanitized values and list of ignored keys.
	 */
	public function sanitize_properties( string $type, array $input ): array {

		$allowed = $this->allowed_properties( $type );
		$catalog = $this->properties();
		$values  = [];
		$ignored = [];

		foreach ( $input as $key => $value ) {
			if ( ! in_array( $key, $allowed, true ) || ! isset( $catalog[ $key ] ) ) {
				$ignored[] = $key;

				continue;
			}

			$sanitizer = $catalog[ $key ]['sanitize'] ?? null;

			// Defensive: a third-party extension may register a property with a non-callable
			// sanitizer through the `wpforms_integrations_abilities_field_registry_properties`
			// filter. Drop the property to `ignored` instead of crashing on `call_user_func`.
			if ( ! is_callable( $sanitizer ) ) {
				$ignored[] = $key;

				continue;
			}

			$values[ $key ] = call_user_func( $sanitizer, $value );
		}

		return [
			'values'  => $values,
			'ignored' => $ignored,
		];
	}

	/**
	 * Flat input-properties JSON schema for add-field and update-field.
	 *
	 * @since 1.10.2
	 *
	 * @return array
	 */
	public function input_properties_schema(): array {

		$properties = [];

		foreach ( $this->properties() as $key => $definition ) {
			$properties[ $key ] = $definition['schema'];
		}

		return [
			'type'                 => 'object',
			'properties'           => $properties,
			'additionalProperties' => false,
		];
	}

	/**
	 * Full JSON schema for a single field item used by create-form's fields array.
	 *
	 * The type is intentionally an unconstrained string so the FormMutator preflight
	 * callback owns every "this type is not supported here" response with HTTP 422
	 * `wpforms_field_type_unavailable`, covering both Pro-on-Lite and entirely unknown
	 * types under one contract. Discoverable types are advertised via the
	 * describe-editing-schema ability.
	 *
	 * @since 1.10.2
	 *
	 * @return array
	 */
	public function field_item_schema(): array {

		return [
			'type'                 => 'object',
			'properties'           => array_merge(
				[
					'type' => [
						'type' => 'string',
					],
				],
				$this->input_properties_schema()['properties']
			),
			'required'             => [ 'type' ],
			'additionalProperties' => false,
		];
	}

	/**
	 * Describe available types and their properties for the discovery ability.
	 *
	 * @since 1.10.2
	 *
	 * @return array
	 */
	public function describe(): array {

		$catalog = $this->properties();
		$types   = $this->types();
		$out     = [];

		foreach ( $this->available_types() as $type ) {
			$props = [];

			foreach ( $this->allowed_properties( $type ) as $key ) {
				$props[] = [
					'key'    => $key,
					'schema' => $catalog[ $key ]['schema'] ?? [],
				];
			}

			$out[] = [
				'type'           => $type,
				'label'          => $types[ $type ]['label'] ?? $type,
				'properties'     => $props,
				'required_props' => $this->required_properties( $type ),
			];
		}

		return $out;
	}

	/**
	 * Sanitize a boolean-ish value to a WPForms-style string flag.
	 *
	 * Delegates to `rest_sanitize_boolean()` so that string transports (REST query
	 * string, form-encoded body) coerce correctly: `"false"`, `"0"`, `"off"`, `"no"`
	 * become false, otherwise PHP would treat any non-empty string — including the
	 * literal `"false"` — as truthy.
	 *
	 * @since 1.10.2
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string '1' or ''.
	 */
	protected function sanitize_bool( $value ): string {

		return rest_sanitize_boolean( $value ) ? '1' : '';
	}

	/**
	 * Sanitize an ordered list of label/value choice objects.
	 *
	 * @since 1.10.2
	 *
	 * @param mixed $choices Raw choices list.
	 *
	 * @return array Ordered list of sanitized choice arrays.
	 */
	protected function sanitize_choices( $choices ): array {

		if ( ! is_array( $choices ) ) {
			return [];
		}

		$clean = [];

		foreach ( $choices as $choice ) {
			if ( ! is_array( $choice ) || ! isset( $choice['label'] ) ) {
				continue;
			}

			$clean[] = [
				'label' => sanitize_text_field( $choice['label'] ),
				'value' => isset( $choice['value'] ) ? sanitize_text_field( $choice['value'] ) : '',
			];
		}

		return $clean;
	}
}