<?php
/**
 * Page composition ability schemas.
 *
 * @package LolaCoreForBricks
 */

declare(strict_types=1);

namespace LolaCoreForBricks\Schemas;

use LolaCoreForBricks\AbilitiesProvider;

/**
 * Door 1 schemas for B8 composition abilities.
 */
class CompositionSchemas
{
    /**
     * @return array<string, array<string, mixed>>
     */
    public static function define(): array
    {
        $dryRun = [
            'dry_run' => [
                'type'        => 'boolean',
                'description' => 'Preview the write without saving changes.',
            ],
        ];

        $page = [
            'post_id' => [
                'type'        => 'integer',
                'description' => 'WordPress post or page ID.',
            ],
            'area'    => [
                'type'        => 'string',
                'description' => 'Page area: content, header, or footer.',
            ],
        ];

        $placement = [
            'parent_id'    => [
                'type'        => 'string',
                'description' => 'Parent element ID. Empty inserts at the root of the area.',
            ],
            'position'     => [
                'type'        => 'string',
                'description' => 'Placement: child, before, or after.',
            ],
            'reference_id' => [
                'type'        => 'string',
                'description' => 'Sibling element ID when position is before or after.',
            ],
        ];

        return [
            'getPageStructure' => [
                'description' => 'Summarize the Bricks element tree for a page area. Use depth and expand to inspect one branch instead of dumping the whole page.',
                'category'    => AbilitiesProvider::CATEGORY,
                'keywords'    => [
                    'exact' => ['page structure', 'element tree', 'estructura de pagina', 'arbol de elementos'],
                    'stem'  => ['structure', 'tree', 'estructura', 'elemento'],
                ],
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => array_merge($page, [
                        'depth'  => [
                            'type'        => 'integer',
                            'description' => 'How many nested levels to include (default 2).',
                        ],
                        'expand' => [
                            'type'        => 'string',
                            'description' => 'Element ID whose branch should be expanded in full.',
                        ],
                    ]),
                    'required'   => ['post_id'],
                ],
            ],
            'insertElement' => [
                'description' => 'Insert a Bricks element into a page area as a child or sibling. Rejects code-execution elements. Call with dry_run first.',
                'category'    => AbilitiesProvider::CATEGORY,
                'keywords'    => [
                    'exact' => ['insert element', 'add section', 'insertar elemento'],
                    'stem'  => ['insert', 'add', 'elemento'],
                ],
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => array_merge($dryRun, $page, $placement, [
                        'name'     => [
                            'type'        => 'string',
                            'description' => 'Bricks element type (section, container, heading, text, …).',
                        ],
                        'settings' => ['type' => 'object'],
                    ]),
                    'required'   => ['post_id', 'name'],
                ],
            ],
            'moveElement' => [
                'description' => 'Move a Bricks element to another parent or position without breaking parent/children links. Call with dry_run first.',
                'category'    => AbilitiesProvider::CATEGORY,
                'keywords'    => [
                    'exact' => ['move element', 'mover elemento', 'reordenar'],
                    'stem'  => ['move', 'mover'],
                ],
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => array_merge($dryRun, $page, $placement, [
                        'element_id' => ['type' => 'string'],
                    ]),
                    'required'   => ['post_id', 'element_id'],
                ],
            ],
            'duplicateElement' => [
                'description' => 'Duplicate a Bricks element branch and assign new IDs to every nested element. Call with dry_run first.',
                'category'    => AbilitiesProvider::CATEGORY,
                'keywords'    => [
                    'exact' => ['duplicate element', 'duplicar elemento', 'clone section'],
                    'stem'  => ['duplicate', 'duplicar', 'clone'],
                ],
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => array_merge($dryRun, $page, [
                        'element_id' => ['type' => 'string'],
                    ]),
                    'required'   => ['post_id', 'element_id'],
                ],
            ],
            'deleteElement' => [
                'description' => 'Remove a Bricks element and its nested children from a page area. Call with dry_run first to review what will be removed.',
                'category'    => AbilitiesProvider::CATEGORY,
                'keywords'    => [
                    'exact' => ['delete element', 'remove section', 'quitar elemento'],
                    'stem'  => ['delete', 'remove', 'quitar'],
                ],
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => array_merge($dryRun, $page, [
                        'element_id' => ['type' => 'string'],
                    ]),
                    'required'   => ['post_id', 'element_id'],
                ],
            ],
        ];
    }
}
