<?php

declare(strict_types=1);

namespace App\Framework\View\Contracts;

use App\Framework\View\Dom\Node;

/**
 * StaticComponent Interface
 *
 * For server-side rendered components without state management.
 * Counterpart to LiveComponentContract for static HTML generation.
 *
 * Constructor Contract:
 * - Components MUST accept: __construct(string $content, array $attributes = [])
 * - $content: Inner HTML/text content from template
 * - $attributes: Key-value pairs from template attributes
 *
 * Returns HTML Node Tree instead of strings for:
 * - Type safety and validation
 * - AST manipulation (CSP, sanitization, transformations)
 * - Better testability
 * - Consistency with DomTemplateParser
 *
 * Example Implementation:
 * ```php
 * #[ComponentName('button')]
 * final readonly class Button implements StaticComponent
 * {
 *     private string $variant;
 *     private string $content;
 *
 *     public function __construct(string $content, array $attributes = [])
 *     {
 *         $this->content = $content;
 *         $this->variant = $attributes['variant'] ?? 'primary';
 *     }
 *
 *     public function getRootNode(): Node
 *     {
 *         $button = new ElementNode('button');
 *         $button->setAttribute('class', "btn btn-{$this->variant}");
 *         $button->appendChild(new TextNode($this->content));
 *         return $button;
 *     }
 * }
 * ```
 *
 * Template Usage:
 * ```html
 * <x-button variant="primary">Click Me</x-button>
 * ```
 *
 * Renders to:
 * ```html
 * <button class="btn btn-primary">Click Me</button>
 * ```
 */
interface StaticComponent
{
    /**
     * Get the root node of this component's HTML tree
     *
     * Returns the root node (typically ElementNode or DocumentNode) that represents
     * this component's HTML structure. The tree will be rendered to HTML by HtmlRenderer.
     *
     * @return Node Root node of the component tree
     */
    public function getRootNode(): Node;
}
