<?php
/**
 * Custom Fields — public helpers for themes and integrations.
 *
 * @package CustomFields
 * @since 1.0.0
 */

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

if ( ! function_exists( 'wps_cf_resolve_meta_key' ) ) {
	/**
	 * Return the stored meta key for a field.
	 *
	 * @param string $group_key  Field group key.
	 * @param string $field_name Field key from the builder.
	 */
	function wps_cf_resolve_meta_key( string $group_key, string $field_name ): string {
		unset( $group_key );

		return $field_name;
	}
}

if ( ! function_exists( 'wps_cf_get' ) ) {
	/**
	 * Get a custom field value for a post.
	 *
	 * @param string   $name    Stored field key.
	 * @param int|null $post_id Post ID (defaults to current post).
	 * @param mixed    $default Fallback when no value is stored.
	 * @return mixed
	 */
	function wps_cf_get( string $name, ?int $post_id = null, mixed $default = '' ): mixed {
		$post_id = $post_id ?? (int) get_the_ID();
		if ( $post_id <= 0 || $name === '' ) {
			return $default;
		}

		$value = get_post_meta( $post_id, $name, true );
		if ( $value === '' || $value === null ) {
			return $default;
		}

		return $value;
	}
}

if ( ! function_exists( 'wps_cf_get_field' ) ) {
	/**
	 * Get a field value using the group key and field key.
	 *
	 * @param string   $group_key  Field group key.
	 * @param string   $field_name Field key from the builder.
	 * @param int|null $post_id    Post ID (defaults to current post).
	 * @param mixed    $default    Fallback when no value is stored.
	 * @return mixed
	 */
	function wps_cf_get_field( string $group_key, string $field_name, ?int $post_id = null, mixed $default = '' ): mixed {
		$located = \CustomFields\FieldOutput::locateField( $group_key, $field_name );
		if ( $located === null ) {
			return $default;
		}

		$meta = \CustomFields\MetaKeys::resolve( $group_key, $located['field'] );
		if ( $meta === '' ) {
			return $default;
		}

		return wps_cf_get( $meta, $post_id, $default );
	}
}

if ( ! function_exists( 'wps_cf_get_term' ) ) {
	/**
	 * Get a custom field value for a taxonomy term.
	 *
	 * @param string $name    Stored field key.
	 * @param int    $term_id Term ID.
	 * @param mixed  $default Fallback when no value is stored.
	 * @return mixed
	 */
	function wps_cf_get_term( string $name, int $term_id, mixed $default = '' ): mixed {
		if ( $term_id <= 0 || $name === '' ) {
			return $default;
		}

		$value = get_term_meta( $term_id, $name, true );
		if ( $value === '' || $value === null ) {
			return $default;
		}

		return $value;
	}
}

if ( ! function_exists( 'wps_cf_get_link' ) ) {
	/**
	 * Get a link field value as a normalized array.
	 *
	 * @param string   $name    Field key.
	 * @param int|null $post_id Post ID (defaults to current post).
	 * @return array{url: string, title: string, target: string}
	 */
	function wps_cf_get_link( string $name, ?int $post_id = null ): array {
		$value = wps_cf_get( $name, $post_id, [] );
		if ( ! is_array( $value ) ) {
			return [ 'url' => '', 'title' => '', 'target' => '' ];
		}

		return [
			'url'    => (string) ( $value['url'] ?? '' ),
			'title'  => (string) ( $value['title'] ?? '' ),
			'target' => (string) ( $value['target'] ?? '' ),
		];
	}
}

if ( ! function_exists( 'wps_cf_get_image_url' ) ) {
	/**
	 * Resolve an image/file field value (attachment ID) to a URL.
	 *
	 * @param mixed  $value Attachment ID.
	 * @param string $size  Image size for image attachments.
	 * @return string
	 */
	function wps_cf_get_image_url( mixed $value, string $size = 'full' ): string {
		$id = (int) $value;
		if ( $id <= 0 ) {
			return '';
		}

		$url = wp_get_attachment_image_url( $id, $size );
		if ( is_string( $url ) && $url !== '' ) {
			return $url;
		}

		$url = wp_get_attachment_url( $id );

		return is_string( $url ) ? $url : '';
	}
}

if ( ! function_exists( 'wps_cf_format_media' ) ) {
	/**
	 * Format a media field value according to return format.
	 *
	 * @param mixed  $value  Stored attachment ID.
	 * @param string $format id|url.
	 * @param string $size   Image size when returning a URL.
	 * @return int|string
	 */
	function wps_cf_format_media( mixed $value, string $format = 'url', string $size = 'full' ): int|string {
		$id = (int) $value;
		if ( $id <= 0 ) {
			return $format === 'id' ? 0 : '';
		}

		if ( $format === 'id' ) {
			return $id;
		}

		return wps_cf_get_image_url( $id, $size );
	}
}

if ( ! function_exists( 'wps_cf_get_integratable_fields' ) ) {
	/**
	 * List fields available for blocks, shortcodes, and page builders.
	 *
	 * @return array<int, array<string, string>>
	 */
	function wps_cf_get_integratable_fields(): array {
		return \CustomFields\FieldOutput::integratableFields();
	}
}

if ( ! function_exists( 'wps_cf_render_field' ) ) {
	/**
	 * Render a custom field for templates and integrations.
	 *
	 * @param array<string, mixed> $args format, default
	 */
	function wps_cf_render_field( string $group_key, string $field_name, ?int $post_id = null, array $args = [] ): string {
		return \CustomFields\FieldOutput::render( $group_key, $field_name, $post_id, $args );
	}
}

if ( ! function_exists( 'wps_cf_get_display' ) ) {
	/**
	 * Get a formatted display value for a custom field.
	 */
	function wps_cf_get_display( string $group_key, string $field_name, ?int $post_id = null, mixed $default = '' ): mixed {
		return \CustomFields\FieldOutput::getDisplay( $group_key, $field_name, $post_id, $default );
	}
}
