<?php
declare(strict_types=1);

namespace ROITheme\Shared\Domain\Exceptions;

/**
 * ComponentNotFoundException - Excepción de Dominio para componente no encontrado
 *
 * RESPONSABILIDAD: Representar errores cuando un componente solicitado no existe
 *
 * CUÁNDO LANZAR:
 * - Búsqueda de componente por nombre que no existe en el repositorio
 * - Intento de actualizar/eliminar componente inexistente
 * - Referencia a componente que fue eliminado
 *
 * USO:
 * ```php
 * $component = $repository->findByName($name);
 *
 * if ($component === null) {
 *     throw ComponentNotFoundException::withName($name);
 * }
 * ```
 *
 * @package ROITheme\Shared\Domain\Exceptions
 */
class ComponentNotFoundException extends \RuntimeException
{
    /**
     * Constructor
     *
     * @param string $message Mensaje de error
     * @param int $code Código de error (opcional)
     * @param \Throwable|null $previous Excepción anterior (opcional)
     */
    public function __construct(
        string $message,
        int $code = 0,
        ?\Throwable $previous = null
    ) {
        parent::__construct($message, $code, $previous);
    }

    /**
     * Crear excepción para componente no encontrado por nombre
     *
     * @param string $componentName
     * @return self
     */
    public static function withName(string $componentName): self
    {
        return new self(
            sprintf('Component "%s" not found', $componentName)
        );
    }

    /**
     * Crear excepción para componente no encontrado por ID
     *
     * @param int $componentId
     * @return self
     */
    public static function withId(int $componentId): self
    {
        return new self(
            sprintf('Component with ID %d not found', $componentId)
        );
    }
}