<?php
/**
 * JSON Schema fragments shared by the abilities.
 *
 * @package SeebAbilities
 */

namespace SeebAbilities\Support;

defined( 'ABSPATH' ) || exit;

/**
 * Schema helpers.
 */
final class Schema {

	/**
	 * Object schema. Without required properties, the input defaults to an empty object so the
	 * ability can be called without input.
	 *
	 * @param array    $properties Properties.
	 * @param string[] $required   Required property names.
	 *
	 * @return array
	 */
	public static function input( array $properties, array $required = [] ): array {

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

		if ( $required ) {
			$schema['required'] = $required;
		} else {
			$schema['default'] = [];
		}

		return $schema;
	}

	/**
	 * Integer ID.
	 *
	 * @param string $description Description.
	 *
	 * @return array
	 */
	public static function id( string $description ): array {
		return [
			'type'        => 'integer',
			'minimum'     => 1,
			'description' => $description,
		];
	}

	/**
	 * String property.
	 *
	 * @param string $description Description.
	 * @param array  $extra       Additional schema keywords.
	 *
	 * @return array
	 */
	public static function string( string $description, array $extra = [] ): array {
		return array_merge(
			[
				'type'        => 'string',
				'description' => $description,
			],
			$extra
		);
	}

	/**
	 * Boolean property.
	 *
	 * @param string $description   Description.
	 * @param bool   $default_value Default value.
	 *
	 * @return array
	 */
	public static function bool( string $description, bool $default_value = false ): array {
		return [
			'type'        => 'boolean',
			'description' => $description,
			'default'     => $default_value,
		];
	}

	/**
	 * Enum property.
	 *
	 * @param string[] $values        Allowed values.
	 * @param string   $description   Description.
	 * @param string   $default_value Default value.
	 *
	 * @return array
	 */
	public static function enum( array $values, string $description, string $default_value = '' ): array {

		$schema = [
			'type'        => 'string',
			'enum'        => $values,
			'description' => $description,
		];

		if ( '' !== $default_value ) {
			$schema['default'] = $default_value;
		}

		return $schema;
	}

	/**
	 * Pagination properties.
	 *
	 * @param int $default_per_page Default page size.
	 * @param int $max_per_page     Maximum page size.
	 *
	 * @return array
	 */
	public static function pagination( int $default_per_page = 20, int $max_per_page = 100 ): array {
		return [
			'per_page' => [
				'type'        => 'integer',
				'minimum'     => 1,
				'maximum'     => $max_per_page,
				'default'     => $default_per_page,
				'description' => __( 'Number of items per page.', 'seeb-abilities' ),
			],
			'page'     => [
				'type'        => 'integer',
				'minimum'     => 1,
				'default'     => 1,
				'description' => __( 'Page number.', 'seeb-abilities' ),
			],
		];
	}

	/**
	 * Order direction property.
	 *
	 * @return array
	 */
	public static function order(): array {
		return self::enum( [ 'asc', 'desc' ], __( 'Sort direction.', 'seeb-abilities' ), 'desc' );
	}

	/**
	 * Output schema of a paginated list.
	 *
	 * @param string $description What the items are.
	 *
	 * @return array
	 */
	public static function list_output( string $description ): array {
		return [
			'type'       => 'object',
			'properties' => [
				'items'       => [
					'type'        => 'array',
					'description' => $description,
				],
				'total'       => [ 'type' => 'integer' ],
				'total_pages' => [ 'type' => 'integer' ],
				'page'        => [ 'type' => 'integer' ],
			],
		];
	}

	/**
	 * Output schema of a single object.
	 *
	 * @param string $description What the object is.
	 *
	 * @return array
	 */
	public static function object_output( string $description ): array {
		return [
			'type'        => 'object',
			'description' => $description,
		];
	}

	/**
	 * Properties that identify where a block ability works: a post or a template.
	 *
	 * @return array
	 */
	public static function block_target(): array {
		return [
			'id'            => self::id( __( 'ID of the post, page, pattern or navigation menu (wp_navigation). Use either "id" or "template".', 'seeb-abilities' ) ),
			'template'      => self::string( __( 'ID of a template or template part, e.g. "twentytwentyfive//home" (see templates-list). Use either "id" or "template".', 'seeb-abilities' ) ),
			'template_type' => self::enum( [ 'wp_template', 'wp_template_part' ], __( 'Whether "template" is a template or a template part. Detected automatically when omitted.', 'seeb-abilities' ) ),
		];
	}

	/**
	 * Block path property.
	 *
	 * @param string $description Description.
	 *
	 * @return array
	 */
	public static function block_path( string $description = '' ): array {
		return self::string(
			'' !== $description ? $description : __( 'Path of the block as returned by post-blocks-get, e.g. "2" for the third top-level block or "2.0" for the first block inside it.', 'seeb-abilities' ),
			[ 'pattern' => '^\d+(\.\d+)*$' ]
		);
	}

	/**
	 * Insert position properties.
	 *
	 * @return array
	 */
	public static function insert_position(): array {
		return [
			'position' => self::enum(
				[ 'start', 'end', 'before', 'after', 'inside_start', 'inside_end' ],
				__( 'Where to insert: at the start or end of the content, before or after the block at "path", or as the first or last inner block of the block at "path".', 'seeb-abilities' ),
				'end'
			),
			'path'     => self::block_path( __( 'Path of the reference block. Required for before, after, inside_start and inside_end.', 'seeb-abilities' ) ),
		];
	}
}