<?php

declare(strict_types=1);

namespace Sarcio\WordPress\Extension;

use Closure;
use Sarcio\WordPress\Assistant\Ability;
use Sarcio\WordPress\Assistant\Overlay;

/**
 * How another plugin extends Sarcio. The plugin hands one instance to
 * `do_action('sarcio_loaded', $api)` on `init` (priority 0), once it has
 * booted and translations can load; an extension checks
 * `version()` against the versions it supports and registers from that hook
 * only.
 *
 * `version()` is this API's version, not the plugin's: it changes only when
 * this surface does. A minor bump adds; a major bump breaks, and the plugin
 * keeps the previous major working for one release.
 *
 * @api
 */
final class Api
{
    public const VERSION = '1.0';

    private const NAME = '/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/';

    public function version(): string
    {
        return self::VERSION;
    }

    public function pluginVersion(): string
    {
        return defined('SARCIO_WP_VERSION') ? (string) SARCIO_WP_VERSION : '';
    }

    /**
     * Adds one ability to the assistant's catalog. Refused (false) when the
     * name is malformed, in the `sarcio/` namespace, already taken, or the
     * spec has no run callback.
     */
    public function addAbility(AbilitySpec $spec): bool
    {
        $names = array_merge([$spec->name()], $spec->aliases());
        foreach ($names as $name) {
            if (!preg_match(self::NAME, $name) || str_starts_with($name, 'sarcio/')) {
                return false;
            }
        }
        $run = $spec->run();
        if ($run === null || !in_array($spec->kind(), [AbilitySpec::READ, AbilitySpec::WRITE], true)) {
            return false;
        }
        $stage = $spec->stage();
        $ability = new Ability(
            $spec->name(),
            $spec->label(),
            $spec->kind() === AbilitySpec::WRITE ? Ability::WRITE : Ability::READ,
            $spec->description(),
            $spec->input(),
            $spec->permission() ?? static fn (array $args): bool => current_user_can('manage_options'),
            $run,
            $spec->preview(),
            $spec->undo(),
            $spec->consent(),
            $stage === null ? null : self::stageThroughPreview($spec->name(), $stage),
        );
        return Registry::addAbility($ability, $spec->aliases(), $spec->render());
    }

    private static function stageThroughPreview(string $name, Closure $stage): Closure
    {
        return static fn (array $args, Overlay $overlay): array => $stage($args, new OverlayPreview($overlay, $name));
    }
}