<?php

declare(strict_types=1);

namespace App\Form\Service\Contract;

use App\Form\Model\BookingDtoInterface;

/**
 * Interface for handling dynamic participant form field processing and state modification.
 *
 * Participant field handlers are responsible for processing submitted form data
 * for booking participants and updating the BookingCreateDto accordingly. They also
 * support field state modification based on processed data and business logic.
 * Handlers support dependency management to ensure fields are processed in the correct order.
 */
interface ParticipantFieldHandlerInterface
{
    /**
     * Returns the field name this handler processes.
     */
    public function getFieldName(): string;

    /**
     * Returns field names this handler depends on.
     *
     * @return string[]
     */
    public function getDependencies(): array;

    /**
     * Processes the participant field data from submitted form data and updates the DTO.
     *
     * @param array<string, mixed> $submittedData    The submitted participant form data
     * @param BookingDtoInterface  $bookingDto       The booking DTO to update (create or edit)
     * @param int                  $participantIndex The participant index being processed
     */
    public function processField(array $submittedData, BookingDtoInterface $bookingDto, int $participantIndex): void;

    /**
     * Determines if this handler should process the field based on submitted participant data.
     */
    public function shouldProcess(array $submittedData, int $participantIndex): bool;

    /**
     * Returns field state modifications that should be applied after processing.
     *
     * This method allows handlers to dynamically modify the state of form fields
     * based on the processed data. It's called after processField() and can be used
     * to enable/disable/hide fields based on the handler's processing results.
     *
     * @param array<string, mixed> $submittedData    The submitted participant form data
     * @param BookingDtoInterface  $bookingDto       The booking DTO (potentially modified by processing)
     * @param int                  $participantIndex The participant index being processed
     *
     * @return array<string, array<string, mixed>> Field state modifications indexed by field name
     */
    public function getFieldStateModifications(array $submittedData, BookingDtoInterface $bookingDto, int $participantIndex): array;

    /**
     * Returns field names whose state is affected by this handler's processing.
     *
     * This method declares which form fields have their state modified by this handler.
     * It's used for dependency tracking and determining when field states need to be
     * recalculated during form processing.
     *
     * @return string[] Array of field names that this handler may modify the state of
     */
    public function getAffectedFieldNames(): array;
}