<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Validation;

/**
 * Validates LiveComponent state against derived schema
 *
 * Automatic Schema Derivation:
 * - First getState() call derives schema from actual State VO types
 * - Schema is cached per component class
 * - Subsequent state updates are validated against derived schema
 * - Prevents state drift and runtime type errors
 *
 * Framework Integration:
 * - LiveComponentHandler validates state after action execution
 * - Throws StateValidationException on schema violations
 * - Zero configuration - works automatically
 *
 * State Value Objects:
 * - Components return typed State VOs (CounterState, SearchState, etc.)
 * - State VOs must implement toArray() for serialization
 * - Validation works directly with State VOs
 */
interface StateValidator
{
    /**
     * Derive schema from State Value Object
     *
     * Analyzes State VO structure and creates schema definition.
     * Called on first getState() for each component class.
     *
     * @param object $state State Value Object (e.g., CounterState, SearchState)
     * @return DerivedSchema Schema definition
     */
    public function deriveSchemaFromState(object $state): DerivedSchema;

    /**
     * Validate State VO against derived schema
     *
     * @param object $state State Value Object to validate
     * @param DerivedSchema $schema Expected schema
     * @throws StateValidationException If validation fails
     */
    public function validateState(object $state, DerivedSchema $schema): void;

    /**
     * Check if State VO matches schema without throwing
     *
     * @param object $state State Value Object to validate
     * @param DerivedSchema $schema Expected schema
     * @return ValidationResult Validation result with errors
     */
    public function checkState(object $state, DerivedSchema $schema): ValidationResult;
}
