<?php
/**
 * Directory catalogue: three named staff fields.
 *
 * There is no fourth staff property to assign. The commercial pack
 * replaces this file with a plan-sized occupancy list.
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Config;

use Bookline\Domain\Agent\Agent;
use Bookline\Domain\Edition\EditionDimension;
use Bookline\Domain\Edition\EditionLimitReached;

/**
 * Three named staff fields.
 *
 * @since 1.0.1
 */
final class AgentPlaces {

	/**
	 * Hydrate named fields from occupied slots (keys 1–3).
	 *
	 * @param array<int, Agent> $occupied_by_slot Slot number => occupant.
	 */
	public static function from_occupied( array $occupied_by_slot ): self {
		return new self(
			$occupied_by_slot[1] ?? null,
			$occupied_by_slot[2] ?? null,
			$occupied_by_slot[3] ?? null
		);
	}

	/**
	 * Bind the three named staff fields.
	 *
	 * @param Agent|null $agent_1 First staff field.
	 * @param Agent|null $agent_2 Second staff field.
	 * @param Agent|null $agent_3 Third staff field.
	 */
	public function __construct(
		private ?Agent $agent_1 = null,
		private ?Agent $agent_2 = null,
		private ?Agent $agent_3 = null,
	) {}

	/**
	 * Occupy the first empty named field.
	 *
	 * @param Agent $agent Incoming staff member.
	 * @return int Slot number 1–3.
	 *
	 * @throws EditionLimitReached When agent_1 … agent_3 are all set.
	 */
	public function place( Agent $agent ): int {
		if ( null === $this->agent_1 ) {
			$this->agent_1 = $agent;
			return 1;
		}
		if ( null === $this->agent_2 ) {
			$this->agent_2 = $agent;
			return 2;
		}
		if ( null === $this->agent_3 ) {
			$this->agent_3 = $agent;
			return 3;
		}
		throw new EditionLimitReached( EditionDimension::Agent, 3 );
	}
}