<?php
/**
 * Booking flow step contract (docs/06 §3).
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Domain\Steps;

/**
 * Named, ordered, skippable unit of the booking flow.
 *
 * @since 0.1.0
 */
interface Step {

	/**
	 * Stable step name (e.g. service, datetime).
	 */
	public function name(): string;

	/**
	 * Progress-bar label (British English; presentation may translate).
	 */
	public function label(): string;

	/**
	 * Whether this step should be skipped for the current session.
	 *
	 * @param BookingSession $session Session.
	 */
	public function should_skip( BookingSession $session ): bool;

	/**
	 * Build the client descriptor.
	 *
	 * @param BookingSession $session Session.
	 */
	public function descriptor( BookingSession $session ): StepDescriptor;

	/**
	 * Validate submitted input.
	 *
	 * @param BookingSession       $session Session.
	 * @param array<string, mixed> $input   Payload.
	 */
	public function validate( BookingSession $session, array $input ): ValidationResult;

	/**
	 * Apply validated input, returning a new session instance.
	 *
	 * @param BookingSession       $session Session.
	 * @param array<string, mixed> $input   Payload.
	 */
	public function apply( BookingSession $session, array $input ): BookingSession;
}