<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Enum;

/**
 * Defines the types of interrupts supported by the system.
 *
 * @api
 */
enum InterruptType: string {

  // Confirmation interrupt - Yes/No, Approve/Reject decisions.
  case Confirmation = 'confirmation';

  // Choice interrupt - Single or multiple selection from options.
  case Choice = 'choice';

  // Text interrupt - Free-form text input.
  case Text = 'text';

  // Form interrupt - Full JSON Schema-based form input.
  case Form = 'form';

  // Workflow execution interrupt - parent workflow paused while a dispatched
  // sub-workflow runs to completion. Resolved via cascade from a linked
  // PipelineCompletion sentinel when the sub-pipeline completes.
  case WorkflowExecution = 'workflow_execution';

  // Operational sentinel created against a running pipeline so that other
  // interrupts can wait for the pipeline's completion via the typed
  // linked_interrupt_id column. Resolved by the generic
  // PipelineCompletionSubscriber when the pipeline's
  // PipelineCompletedEvent fires.
  case PipelineCompletion = 'pipeline_completion';

  // Universal schema-driven HITL interrupt. Handler renders proper Drupal
  // widgets from any FlowDrop Schema. Supersedes Confirmation/Choice/Text/Form
  // for new callers; the legacy types remain for backward compatibility with
  // existing stored interrupts.
  case SchemaForm = 'schema_form';

  // Inward Cancel signal — created externally to terminate a running
  // pipeline. The orchestrator polls between jobs, processes the signal
  // (mark pipeline cancelled, cancel outward interrupts), and acknowledges.
  case Cancel = 'cancel';

  // Inward Pause signal — created externally to halt a running pipeline
  // until explicitly resumed. The signal itself is the resume key: when
  // resolved through the inbox or /resume API, the pipeline continues.
  case Pause = 'pause';

  // Timer interrupt — the system clock resolves it instead of a human.
  // Created by Delay/Schedule nodes with a `scheduled_at` fire time; the
  // cron-driven ScheduledInterruptSweeper resolves it once due, resuming
  // the pipeline. Resolving it early through the inbox or /resume API
  // skips the remaining wait.
  case Timer = 'timer';

  /**
   * Gets a human-readable label for the interrupt type.
   *
   * @return string
   *   The label.
   */
  public function label(): string {
    return match ($this) {
      self::Confirmation => 'Confirmation',
      self::Choice => 'Choice',
      self::Text => 'Text Input',
      self::Form => 'Form',
      self::WorkflowExecution => 'Sub-workflow execution',
      self::PipelineCompletion => 'Pipeline completion sentinel',
      self::SchemaForm => 'Schema-driven form',
      self::Cancel => 'Cancel signal',
      self::Pause => 'Pause signal',
      self::Timer => 'Timer',
    };
  }

  /**
   * Gets a description of the interrupt type.
   *
   * @return string
   *   The description.
   */
  public function description(): string {
    return match ($this) {
      self::Confirmation => 'Yes/No or Approve/Reject decision',
      self::Choice => 'Single or multiple selection from options',
      self::Text => 'Free-form text input',
      self::Form => 'Structured form based on JSON Schema',
      self::WorkflowExecution => 'Parent workflow paused while sub-workflow runs',
      self::PipelineCompletion => 'Sentinel waiting for a pipeline run to finish',
      self::SchemaForm => 'Universal HITL with widgets rendered from any FlowDrop Schema',
      self::Cancel => 'Inward signal: terminate a running pipeline',
      self::Pause => 'Inward signal: halt a running pipeline until resumed',
      self::Timer => 'Time-based pause resolved automatically when due',
    };
  }

}
