<?php

declare(strict_types=1);

namespace App\Application\LiveComponents;

use App\Framework\StateManagement\SerializableState;

/**
 * LiveComponent State Interface
 *
 * All component-specific state Value Objects must implement this interface.
 * Provides consistent serialization/deserialization for LiveComponent state management.
 *
 * Extends SerializableState for seamless integration with StateManager infrastructure.
 * This enables domain-specific states to leverage CacheBasedStateManager, InMemoryStateManager,
 * and other StateManager implementations while maintaining full type safety.
 *
 * Examples:
 * - CounterState implements LiveComponentState
 * - SearchState implements LiveComponentState
 * - ShoppingCartState implements LiveComponentState
 *
 * Framework Integration:
 * - LiveComponentHandler validates state after actions
 * - ComponentRegistry uses toArray() for serialization
 * - Client receives state as JSON, sends back as array
 * - StateManager provides persistent state storage with TTL support
 *
 * Type Safety:
 * Components retain fully typed states (e.g., ShoppingCartState, not LiveComponentState)
 * thanks to StateManager's generic type parameter system (@template T of SerializableState).
 */
interface LiveComponentState extends SerializableState
{
    /**
     * Create State VO from array data (from client or storage)
     *
     * @param array $data Raw state data
     * @return self Hydrated state object
     */
    public static function fromArray(array $data): self;

    /**
     * Convert State VO to array for serialization
     *
     * Used for:
     * - JSON responses to client
     * - State validation
     * - Caching
     *
     * @return array Serializable state data
     */
    public function toArray(): array;
}
