<?php
/** Ability definitions for transactional MB Settings Page management. */

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

/** @return array<string,mixed> */
function wpagent_metabox_settings_page_settings_schema(): array {
	$tab_value = array(
		'oneOf' => array(
			array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 100 ),
			array(
				'type' => 'object',
				'properties' => array(
					'label' => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 100 ),
					'icon'  => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 500 ),
				),
				'required' => array( 'label' ),
				'additionalProperties' => false,
			),
		),
	);
	return array(
		'type' => 'object',
		'properties' => array(
			'id'              => array( 'type' => 'string', 'pattern' => '^[a-z][a-z0-9_-]{0,63}$', 'maxLength' => 64 ),
			'option_name'     => array( 'type' => 'string', 'pattern' => '^[A-Za-z_][A-Za-z0-9_.:-]{0,190}$', 'maxLength' => 191 ),
			'class'           => array( 'type' => 'string', 'maxLength' => 1000 ),
			'menu_title'      => array( 'type' => 'string', 'maxLength' => 200 ),
			'page_title'      => array( 'type' => 'string', 'maxLength' => 200 ),
			'capability'      => array( 'type' => 'string', 'pattern' => '^[a-z][a-z0-9_]{0,63}$', 'maxLength' => 64 ),
			'icon_url'        => array( 'type' => 'string', 'maxLength' => 500 ),
			'position'        => array( 'type' => 'integer', 'minimum' => 1, 'maximum' => 999 ),
			'parent'          => array( 'type' => 'string', 'maxLength' => 190 ),
			'submenu_title'   => array( 'type' => 'string', 'maxLength' => 200 ),
			'help_tabs'       => array(
				'type' => 'array',
				'maxItems' => 20,
				'items' => array(
					'type' => 'object',
					'properties' => array(
						'title'    => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 100 ),
						'content'  => array( 'type' => 'string', 'maxLength' => 10000 ),
						'priority' => array( 'type' => 'integer', 'minimum' => 0, 'maximum' => 1000 ),
					),
					'required' => array( 'title', 'content', 'priority' ),
					'additionalProperties' => false,
				),
			),
			'style'           => array( 'type' => 'string', 'enum' => array( 'boxes', 'no-boxes' ) ),
			'columns'         => array( 'type' => 'integer', 'enum' => array( 1, 2 ) ),
			'tabs'            => array( 'type' => 'object', 'maxProperties' => 20, 'additionalProperties' => $tab_value ),
			'tab_style'       => array( 'type' => 'string', 'enum' => array( 'default', 'left' ) ),
			'submit_button'   => array( 'type' => 'string', 'maxLength' => 200 ),
			'message'         => array( 'type' => 'string', 'maxLength' => 500 ),
			'customizer'      => array( 'type' => 'boolean' ),
			'customizer_only' => array( 'type' => 'boolean' ),
			'network'         => array( 'type' => 'boolean' ),
		),
		'required' => array( 'id', 'option_name' ),
		'additionalProperties' => false,
	);
}

/** @return array<string,mixed> */
function wpagent_metabox_settings_page_runtime_schema(): array {
	$schema = wpagent_metabox_settings_page_settings_schema();
	$schema['type'] = array( 'object', 'null' );
	return $schema;
}

/** @return array<string,mixed> */
function wpagent_metabox_settings_page_state_schema(): array {
	$settings = wpagent_metabox_settings_page_settings_schema();
	return array(
		'type' => 'object',
		'properties' => array(
			'id' => array( 'type' => 'integer', 'minimum' => 1 ),
			'title' => array( 'type' => 'string', 'maxLength' => 200 ),
			'slug' => array( 'type' => 'string', 'pattern' => '^[a-z][a-z0-9_-]{0,63}(?:__trashed(?:-[1-9][0-9]{0,3})?)?$', 'maxLength' => 78 ),
			'status' => array( 'type' => 'string', 'enum' => array( 'publish', 'draft', 'trash' ) ),
			'settings' => $settings,
			'runtime' => wpagent_metabox_settings_page_runtime_schema(),
			'hash' => array( 'type' => 'string', 'pattern' => '^[a-f0-9]{64}$' ),
		),
		'required' => array( 'id', 'title', 'slug', 'status', 'settings', 'runtime', 'hash' ),
		'additionalProperties' => false,
	);
}

/** @return array<string,mixed> */
function wpagent_metabox_settings_page_ability( string $label, string $description, array $input, array $output, string $callback, bool $readonly = false, bool $destructive = false ): array {
	return array(
		'label' => $label,
		'description' => $description,
		'category' => 'wp-agent',
		'input_schema' => $input,
		'output_schema' => $output,
		'execute_callback' => $callback,
		'permission_callback' => 'wpagent_perm_manage_options',
		'meta' => array(
			'show_in_rest' => true,
			'annotations' => array( 'readonly' => $readonly, 'destructive' => $destructive, 'idempotent' => $readonly ),
		),
	);
}

/** @return array<string,mixed> */
function wpagent_ability_list_meta_box_settings_pages(): array {
	return wpagent_metabox_settings_page_ability(
		__( 'Meta-Box-Einstellungsseiten auflisten', 'wp-agent-companion' ),
		__( 'Listet persistente MB-Settings-Page-Definitionen mit Laufzeitzustand und Konflikthash.', 'wp-agent-companion' ),
		array( 'type' => 'object', 'properties' => array( 'search' => array( 'type' => 'string', 'maxLength' => 100 ), 'limit' => array( 'type' => 'integer', 'minimum' => 1, 'maximum' => 100, 'default' => 50 ), 'offset' => array( 'type' => 'integer', 'minimum' => 0, 'maximum' => 10000, 'default' => 0 ) ), 'additionalProperties' => false ),
		array( 'type' => 'object', 'properties' => array( 'settings_pages' => array( 'type' => 'array', 'maxItems' => 100, 'items' => wpagent_metabox_settings_page_state_schema() ), 'total' => array( 'type' => 'integer', 'minimum' => 0 ) ), 'required' => array( 'settings_pages', 'total' ), 'additionalProperties' => false ),
		'wpagent_metabox_list_settings_pages',
		true
	);
}

/** @return array<string,mixed> */
function wpagent_ability_get_meta_box_settings_page(): array {
	return wpagent_metabox_settings_page_ability(
		__( 'Meta-Box-Einstellungsseite lesen', 'wp-agent-companion' ),
		__( 'Liest eine persistente MB-Settings-Page-Definition samt aktivem Laufzeitzustand.', 'wp-agent-companion' ),
		array( 'type' => 'object', 'properties' => array( 'id' => array( 'type' => 'integer', 'minimum' => 1 ) ), 'required' => array( 'id' ), 'additionalProperties' => false ),
		wpagent_metabox_settings_page_state_schema(),
		'wpagent_metabox_get_settings_page',
		true
	);
}

/** @return array<string,mixed> */
function wpagent_ability_create_meta_box_settings_page(): array {
	return wpagent_metabox_settings_page_ability(
		__( 'Meta-Box-Einstellungsseite erstellen', 'wp-agent-companion' ),
		__( 'Erstellt eine geprüfte MB-Settings-Page-Definition und verifiziert Builder- sowie Laufzeitzustand.', 'wp-agent-companion' ),
		array(
			'type' => 'object',
			'properties' => array(
				'title' => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 200 ),
				'status' => array( 'type' => 'string', 'enum' => array( 'publish', 'draft' ), 'default' => 'publish' ),
				'settings' => wpagent_metabox_settings_page_settings_schema(),
			),
			'required' => array( 'title', 'settings' ),
			'additionalProperties' => false,
		),
		wpagent_metabox_settings_page_state_schema(),
		'wpagent_metabox_create_settings_page'
	);
}

/** @return array<string,mixed> */
function wpagent_ability_update_meta_box_settings_page(): array {
	$definition = wpagent_metabox_settings_page_ability(
		__( 'Meta-Box-Einstellungsseite ändern: manuell erforderlich', 'wp-agent-companion' ),
		__( 'Meta Box bietet für Einstellungsseiten keine speicheratomare Vergleichsoperation. Diese registrierte Schreib-Ability lehnt Änderungen deshalb ab, damit Dashboard-Änderungen nicht überschrieben werden.', 'wp-agent-companion' ),
		array(
			'type' => 'object',
			'properties' => array(
				'id' => array( 'type' => 'integer', 'minimum' => 1 ),
				'expected_hash' => array( 'type' => 'string', 'pattern' => '^[a-f0-9]{64}$' ),
				'title' => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 200 ),
				'status' => array( 'type' => 'string', 'enum' => array( 'publish', 'draft' ) ),
				'settings' => wpagent_metabox_settings_page_settings_schema(),
			),
			'required' => array( 'id', 'expected_hash', 'settings' ),
			'additionalProperties' => false,
		),
		array( 'type' => 'object', 'properties' => array( 'manual_action_required' => array( 'type' => 'boolean' ) ), 'required' => array( 'manual_action_required' ), 'additionalProperties' => false ),
		'wpagent_metabox_update_settings_page'
	);
	$definition['meta']['annotations']['manual_only'] = true;
	return $definition;
}

/** @return array<string,mixed> */
function wpagent_ability_delete_meta_box_settings_page(): array {
	$definition = wpagent_metabox_settings_page_ability(
		__( 'Meta-Box-Einstellungsseite löschen: manuell erforderlich', 'wp-agent-companion' ),
		__( 'Meta Box bietet für Einstellungsseiten keine speicheratomare Compare-and-Delete-Operation. Diese registrierte Schreib-Ability ändert oder verschiebt deshalb keine Definition.', 'wp-agent-companion' ),
		array(
			'type' => 'object',
			'properties' => array(
				'id' => array( 'type' => 'integer', 'minimum' => 1 ),
				'expected_hash' => array( 'type' => 'string', 'pattern' => '^[a-f0-9]{64}$' ),
			),
			'required' => array( 'id', 'expected_hash' ),
			'additionalProperties' => false,
		),
		array( 'type' => 'object', 'properties' => array( 'manual_action_required' => array( 'type' => 'boolean' ) ), 'required' => array( 'manual_action_required' ), 'additionalProperties' => false ),
		'wpagent_metabox_delete_settings_page',
		false,
		true
	);
	$definition['meta']['annotations']['manual_only'] = true;
	return $definition;
}
