<?php
/**
 * REST argument schemas.
 *
 * Every route declares its arguments so WordPress validates and sanitizes input
 * before the handler runs, and invalid requests get a consistent 400
 * `rest_invalid_param` error that names the field.
 *
 * @package KarmaDocs
 */

namespace KarmaDocs\Rest;

defined( 'ABSPATH' ) || exit;

/**
 * Argument definitions shared by the controllers.
 */
class Args {

	/**
	 * Builder node reference: "c12" (category) or "a34" (article).
	 */
	const NODE_PATTERN = '^[ca][0-9]+$';

	/**
	 * Positive integer id.
	 *
	 * @param bool   $required    Required.
	 * @param string $description Description.
	 * @return array
	 */
	public static function id( $required = true, $description = '' ) {
		return array(
			'type'        => 'integer',
			'minimum'     => $required ? 1 : 0,
			'required'    => $required,
			'description' => $description,
		);
	}

	/**
	 * Plain text.
	 *
	 * @param int  $max      Maximum length.
	 * @param bool $required Required.
	 * @return array
	 */
	public static function text( $max = 200, $required = false ) {
		return array(
			'type'              => 'string',
			'maxLength'         => $max,
			'required'          => $required,
			'sanitize_callback' => 'sanitize_text_field',
		);
	}

	/**
	 * Multi-line text.
	 *
	 * @param int $max Maximum length.
	 * @return array
	 */
	public static function textarea( $max = 2000 ) {
		return array(
			'type'              => 'string',
			'maxLength'         => $max,
			'sanitize_callback' => 'sanitize_textarea_field',
		);
	}

	/**
	 * One of a fixed list of strings.
	 *
	 * @param string[]    $values   Allowed values.
	 * @param bool        $required Required.
	 * @param string|null $default  Default.
	 * @return array
	 */
	public static function enum( array $values, $required = false, $default = null ) {
		$arg = array(
			'type'     => 'string',
			'enum'     => $values,
			'required' => $required,
		);
		if ( null !== $default ) {
			$arg['default'] = $default;
		}
		return $arg;
	}

	/**
	 * Icon: JSON icon model or a legacy string (see Icons).
	 *
	 * @return array
	 */
	public static function icon() {
		return array(
			'type'              => 'string',
			'maxLength'         => 2000,
			'sanitize_callback' => array( \KarmaDocs\Icons::class, 'sanitize' ),
		);
	}

	/**
	 * Cover image or gradient (see Covers); '' removes it.
	 *
	 * @return array
	 */
	public static function cover() {
		return array(
			'type'              => 'string',
			'maxLength'         => 2000,
			'sanitize_callback' => array( \KarmaDocs\Covers::class, 'sanitize' ),
		);
	}

	/**
	 * Hex color or empty string (to clear).
	 *
	 * @return array
	 */
	public static function color() {
		return array(
			'type'    => 'string',
			'pattern' => '^(#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?)?$',
		);
	}

	/**
	 * Builder node reference, optionally empty (top level).
	 *
	 * @param bool $nullable Allow null / empty.
	 * @return array
	 */
	public static function node( $nullable = true ) {
		if ( ! $nullable ) {
			return array(
				'type'     => 'string',
				'pattern'  => self::NODE_PATTERN,
				'required' => true,
			);
		}
		return array(
			'type'    => array( 'string', 'null' ),
			'pattern' => '^([ca][0-9]+)?$',
		);
	}

	/**
	 * List of node references.
	 *
	 * @return array
	 */
	public static function nodes() {
		return array(
			'type'     => 'array',
			'required' => true,
			'minItems' => 1,
			'maxItems' => 5000,
			'items'    => array(
				'type'    => 'string',
				'pattern' => self::NODE_PATTERN,
			),
		);
	}

	/**
	 * Full tree payload for POST /kbs/{id}/tree.
	 *
	 * @return array
	 */
	public static function tree_items() {
		return array(
			'type'     => 'array',
			'required' => true,
			'maxItems' => 10000,
			'items'    => array(
				'type'                 => 'object',
				'additionalProperties' => false,
				'properties'           => array(
					'id'     => array(
						'type'     => 'string',
						'pattern'  => self::NODE_PATTERN,
						'required' => true,
					),
					'parent' => array(
						'type'    => array( 'string', 'null' ),
						'pattern' => '^([ca][0-9]+)?$',
					),
					'order'  => array(
						'type'    => 'integer',
						'minimum' => 0,
					),
				),
			),
		);
	}

	/**
	 * Knowledge base fields (create / update).
	 *
	 * @param bool $create Creating (name required).
	 * @return array
	 */
	public static function kb_fields( $create ) {
		return array(
			'name'        => self::text( 200, $create ),
			'slug'        => array(
				'type'              => 'string',
				'maxLength'         => 200,
				'sanitize_callback' => 'sanitize_title',
			),
			'description' => self::textarea( 1000 ),
			'icon'        => self::icon(),
			'color'       => self::color(),
			'cover'       => self::cover(),
			'layout'      => self::enum( array( '', 'cards', 'list', 'minimal', 'boxed' ) ),
			'access'      => self::enum( array( 'public', 'logged_in', 'roles' ) ),
			'roles'       => array(
				'type'  => 'array',
				'items' => array( 'type' => 'string' ),
			),
		);
	}

	/**
	 * Optional page number and page size.
	 *
	 * @param int $max_per_page Maximum page size.
	 * @return array
	 */
	public static function pagination( $max_per_page = 100 ) {
		return array(
			'page'     => array(
				'type'    => 'integer',
				'minimum' => 1,
				'default' => 1,
			),
			'per_page' => array(
				'type'    => 'integer',
				'minimum' => 1,
				'maximum' => $max_per_page,
				'default' => 20,
			),
		);
	}

	/**
	 * Adds X-WP-Total / X-WP-TotalPages headers like core collection endpoints.
	 *
	 * @param \WP_REST_Response $response Response.
	 * @param int               $total    Total items.
	 * @param int               $per_page Page size.
	 * @return \WP_REST_Response
	 */
	public static function paginate( $response, $total, $per_page ) {
		$response->header( 'X-WP-Total', (string) (int) $total );
		$response->header( 'X-WP-TotalPages', (string) (int) ceil( $total / max( 1, $per_page ) ) );
		return $response;
	}
}