<?php

declare(strict_types=1);

namespace Drupal\flowdrop_orchestration\Plugin\Orchestrator;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\flowdrop_orchestration\Service\Orchestrator\OrchestratorInterface;

/**
 * Interface for Orchestrator plugins.
 *
 * Orchestrators control how workflows are executed. Different orchestrators
 * provide different execution strategies:
 * - Synchronous: Direct execution in the current request
 * - Asynchronous: Queue-based execution
 * - StateGraph: Stateful execution with checkpointing.
 *
 * Each orchestrator can provide its own configuration form elements by
 * implementing the buildConfigurationForm(), validateConfigurationForm(),
 * and submitConfigurationForm() methods.
 *
 * This interface extends the base OrchestratorInterface for backward
 * compatibility with code that expects the service-based interface.
 *
 * @see \Drupal\flowdrop_orchestration\Attribute\Orchestrator
 * @see \Drupal\flowdrop_orchestration\Plugin\Orchestrator\OrchestratorPluginBase
 * @see \Drupal\flowdrop_orchestration\Service\Orchestrator\OrchestratorInterface
 *
 * @api
 */
interface OrchestratorPluginInterface extends OrchestratorInterface, PluginInspectionInterface {

  /**
   * Builds the orchestrator-specific configuration form elements.
   *
   * Each orchestrator plugin can provide its own form elements for
   * configuration. These elements will be rendered dynamically when the
   * orchestrator is selected in the trigger configuration form.
   *
   * @param array<string, mixed> $form
   *   The form array to add elements to.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current form state.
   * @param array<string, mixed> $settings
   *   Current orchestrator settings from the trigger configuration.
   *
   * @return array<string, mixed>
   *   The form array with orchestrator-specific elements added.
   */
  public function buildConfigurationForm(array $form, FormStateInterface $form_state, array $settings): array;

  /**
   * Validates the orchestrator-specific configuration form.
   *
   * Called during form validation to allow the orchestrator to validate
   * its specific configuration values.
   *
   * @param array<string, mixed> $form
   *   The form array.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current form state.
   */
  public function validateConfigurationForm(array $form, FormStateInterface $form_state): void;

  /**
   * Processes the orchestrator-specific configuration form submission.
   *
   * Extracts and returns the configuration values from the submitted form.
   * These values will be stored in the orchestrator_settings array.
   *
   * @param array<string, mixed> $form
   *   The form array.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current form state.
   *
   * @return array<string, mixed>
   *   The processed configuration values to store.
   */
  public function submitConfigurationForm(array $form, FormStateInterface $form_state): array;

  /**
   * Gets the default configuration for this orchestrator.
   *
   * Returns the default values for this orchestrator's configuration.
   * These defaults are used when no settings have been configured yet.
   *
   * @return array<string, mixed>
   *   The default configuration values.
   */
  public function getDefaultConfiguration(): array;

}
