<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Plugin\InterruptHandler;

use Drupal\Core\Form\FormStateInterface;
use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;

/**
 * Marks an interrupt handler as human-in-the-loop.
 *
 * Plugins implementing this interface appear in the interrupt inbox, can be
 * resolved through the resolve form, and provide their own form-building
 * and extraction logic.
 *
 * @api
 */
interface HitlInterruptHandlerInterface extends InterruptHandlerInterface {

  /**
   * Builds the form fields that resolve this interrupt.
   *
   * Implementations add input elements (textarea, radios, submit buttons,
   * etc.) under the form's standard wrapping. The harness ResolveInterruptForm
   * supplies the surrounding structure (interrupt message, back/cancel
   * actions); plugins only contribute the response-specific fields.
   *
   * @param array<string, mixed> $form
   *   The form structure to mutate.
   * @param \Drupal\Core\Form\FormStateInterface $formState
   *   Current form state.
   * @param \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface $interrupt
   *   The interrupt being resolved.
   *
   * @return array<string, mixed>
   *   The mutated form.
   */
  public function buildResolveForm(array $form, FormStateInterface $formState, FlowDropInterruptInterface $interrupt): array;

  /**
   * Extracts response data from submitted form state.
   *
   * Called from `ResolveInterruptForm::submitForm()` after validation passes.
   * The returned value is what `normalizeResponse()` then canonicalises.
   *
   * @param \Drupal\Core\Form\FormStateInterface $formState
   *   The submitted form state.
   * @param \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface $interrupt
   *   The interrupt being resolved.
   *
   * @return mixed
   *   Raw response, to be passed through `normalizeResponse()`.
   */
  public function extractResponseFromForm(FormStateInterface $formState, FlowDropInterruptInterface $interrupt): mixed;

  /**
   * Validates submitted form values for this interrupt.
   *
   * Implementations call `$formState->setErrorByName()` for any invalid
   * response. Returning normally with no errors means the submission is
   * valid. Default no-op implementations are appropriate when the interrupt
   * has no constraints beyond `#required` (which Drupal enforces).
   */
  public function validateForm(array &$form, FormStateInterface $formState, FlowDropInterruptInterface $interrupt): void;

}
