<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Integrations\Forms;

/**
 * Contract for form plugin integrations.
 */
interface FormAdapterInterface
{
    /**
     * Return unique adapter key.
     *
     * @return string
     */
    public function key(): string;

    /**
     * Return human readable adapter label.
     *
     * @return string
     */
    public function label(): string;

    /**
     * Return whether the form plugin is available.
     *
     * @return bool
     */
    public function isAvailable(): bool;

    /**
     * Register plugin hooks and emit form change notifications.
     *
     * @param callable $onFormChanged Callback signature: fn(string $adapterKey, string|int $formId, array $context): void
     * @return void
     */
    public function registerHooks(callable $onFormChanged): void;

    /**
     * Return shortcode tags used by this form plugin.
     *
     * @return string[]
     */
    public function shortcodes(): array;

    /**
     * Return block names used by this form plugin.
     *
     * @return string[]
     */
    public function blockNames(): array;

    /**
     * Return lightweight candidate needles for SQL prefiltering.
     *
     * @return string[]
     */
    public function candidateNeedles(): array;

    /**
     * Extract form IDs from normalized text from arbitrary storage locations.
     *
     * Adapters must stay agnostic to storage type, builder type, meta keys, and
     * serialization format. The provided text is normalized for storage-only
     * escaping artifacts before extraction.
     *
     * @param string $text Normalized source text.
     * @return string[]
     */
    public function extractFormIdsFromContent(string $text): array;
}
