<?php

declare(strict_types=1);

namespace PrettyLinks\Pro\PrettyBar\Templates;

/**
 * Contract for a Pretty Bar template. A template pairs a rendered HTML
 * document (iframe shell + its branded chrome) with a typed set of
 * options. The dispatcher {@see \PrettyLinks\Pro\PrettyBar\BarRenderer}
 * resolves which template to use for a given link and then calls
 * `render()` with the link row, target URL, and resolved settings.
 */
interface BarTemplate
{
    /**
     * Stable identifier stored in `prli_link_metas.prettybar_template`.
     */
    public function id(): string;

    /**
     * Human-readable name for the admin picker.
     */
    public function label(): string;

    /**
     * Resolved settings for this template, merged with defaults. Shared
     * site-wide settings (logo, attribution) are included too.
     *
     * @return array<string, mixed>
     */
    public function settings(): array;

    /**
     * Render the full HTML document. Implementations must `exit` after
     * emitting output — the iframe shell *is* the entire response.
     *
     * @param array<string, mixed> $link     Hydrated link row.
     * @param string               $target   Resolved redirect target.
     * @param array<string, mixed> $settings Result of {@see self::settings()}.
     */
    public function render(array $link, string $target, array $settings): void;
}
