feat(exclusions): Implement component exclusion system (Plan 99.11)

Adds ability to exclude components from specific:
- Categories (by slug or term_id)
- Post/Page IDs
- URL patterns (substring or regex)

Architecture:
- Domain: Value Objects (CategoryExclusion, PostIdExclusion,
  UrlPatternExclusion, ExclusionRuleSet) + Contracts
- Application: EvaluateExclusionsUseCase +
  EvaluateComponentVisibilityUseCase (orchestrator)
- Infrastructure: WordPressExclusionRepository,
  WordPressPageContextProvider, WordPressServerRequestProvider
- Admin: ExclusionFormPartial (reusable UI),
  ExclusionFieldProcessor, JS toggle

The PageVisibilityHelper now uses the orchestrator UseCase that
combines page-type visibility (Plan 99.10) with exclusion rules.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Shared/Domain/Constants/ExclusionDefaults.php

@@ -0,0 +1,37 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\Constants;
+
+/**
+ * Constantes de exclusion por defecto para componentes
+ *
+ * @package ROITheme\Shared\Domain\Constants
+ */
+final class ExclusionDefaults
+{
+    /**
+     * Configuracion de exclusion por defecto (sin exclusiones)
+     */
+    public const DEFAULT_EXCLUSIONS = [
+        'exclusions_enabled' => false,
+        'exclude_categories' => '[]',
+        'exclude_post_ids' => '[]',
+        'exclude_url_patterns' => '[]',
+    ];
+
+    /**
+     * Lista de campos de exclusion validos
+     */
+    public const EXCLUSION_FIELDS = [
+        'exclusions_enabled',
+        'exclude_categories',
+        'exclude_post_ids',
+        'exclude_url_patterns',
+    ];
+
+    /**
+     * Nombre del grupo en BD
+     */
+    public const GROUP_NAME = '_exclusions';
+}

Shared/Domain/Contracts/ExclusionRepositoryInterface.php

@@ -0,0 +1,36 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\Contracts;
+
+use ROITheme\Shared\Domain\ValueObjects\ExclusionRuleSet;
+
+/**
+ * Contrato para acceder a la configuracion de exclusiones
+ *
+ * Metodos: 3 (cumple ISP < 5 metodos)
+ *
+ * @package ROITheme\Shared\Domain\Contracts
+ */
+interface ExclusionRepositoryInterface
+{
+    /**
+     * Obtiene las exclusiones configuradas para un componente
+     *
+     * @param string $componentName Nombre del componente (kebab-case)
+     * @return ExclusionRuleSet Configuracion de exclusiones
+     */
+    public function getExclusions(string $componentName): ExclusionRuleSet;
+
+    /**
+     * Guarda la configuracion de exclusiones de un componente
+     *
+     * @param ExclusionRuleSet $exclusions Configuracion a guardar
+     */
+    public function saveExclusions(ExclusionRuleSet $exclusions): void;
+
+    /**
+     * Verifica si existe configuracion de exclusiones para un componente
+     */
+    public function hasExclusions(string $componentName): bool;
+}

Shared/Domain/Contracts/PageContextProviderInterface.php

@@ -0,0 +1,33 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\Contracts;
+
+/**
+ * Contrato para obtener el contexto de la pagina actual
+ *
+ * Abstrae la obtencion de datos del contexto actual (WordPress).
+ * Permite testear UseCases sin dependencia de WordPress.
+ *
+ * v1.1: Renombrado de ExclusionEvaluatorInterface (nombre semantico incorrecto)
+ *       El nombre refleja que PROVEE contexto, no que EVALUA.
+ *
+ * Metodos: 1 (cumple ISP < 5 metodos)
+ *
+ * @package ROITheme\Shared\Domain\Contracts
+ */
+interface PageContextProviderInterface
+{
+    /**
+     * Obtiene el contexto actual para evaluacion de exclusiones
+     *
+     * @return array{
+     *     post_id: int,
+     *     categories: array<array{term_id: int, slug: string, name: string}>,
+     *     url: string,
+     *     request_uri: string,
+     *     post_type: string
+     * }
+     */
+    public function getCurrentContext(): array;
+}

Shared/Domain/Contracts/ServerRequestProviderInterface.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\Contracts;
+
+/**
+ * Contrato para obtener datos del request HTTP
+ *
+ * Encapsula el acceso a $_SERVER para:
+ * - Evitar acceso directo a superglobales en Infrastructure
+ * - Permitir testear sin dependencia de $_SERVER
+ *
+ * v1.1: Nuevo - encapsular acceso a $_SERVER
+ *
+ * Metodos: 1 (cumple ISP < 5 metodos)
+ *
+ * @package ROITheme\Shared\Domain\Contracts
+ */
+interface ServerRequestProviderInterface
+{
+    /**
+     * Obtiene el Request URI actual
+     *
+     * @return string URI del request (ej: "/blog/mi-post/")
+     */
+    public function getRequestUri(): string;
+}

Shared/Domain/ValueObjects/CategoryExclusion.php

@@ -0,0 +1,100 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\ValueObjects;
+
+/**
+ * Value Object: Exclusion por categoria
+ *
+ * Evalua si un post pertenece a alguna de las categorias excluidas.
+ * Soporta matching por slug o term_id.
+ *
+ * @package ROITheme\Shared\Domain\ValueObjects
+ */
+final class CategoryExclusion extends ExclusionRule
+{
+    /**
+     * @param array<int|string> $excludedCategories Lista de slugs o IDs de categorias
+     */
+    public function __construct(
+        private readonly array $excludedCategories = []
+    ) {}
+
+    /**
+     * {@inheritdoc}
+     *
+     * Contexto esperado:
+     * - categories: array<array{term_id: int, slug: string, name: string}>
+     */
+    public function matches(array $context): bool
+    {
+        if (!$this->hasValues()) {
+            return false;
+        }
+
+        $postCategories = $context['categories'] ?? [];
+
+        if (empty($postCategories)) {
+            return false;
+        }
+
+        foreach ($postCategories as $category) {
+            // Buscar por slug
+            if (in_array($category['slug'], $this->excludedCategories, true)) {
+                return true;
+            }
+
+            // Buscar por term_id
+            if (in_array($category['term_id'], $this->excludedCategories, true)) {
+                return true;
+            }
+
+            // Buscar por term_id como string (para comparaciones flexibles)
+            if (in_array((string) $category['term_id'], $this->excludedCategories, true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public function hasValues(): bool
+    {
+        return !empty($this->excludedCategories);
+    }
+
+    public function serialize(): string
+    {
+        return json_encode($this->excludedCategories, JSON_UNESCAPED_UNICODE);
+    }
+
+    /**
+     * @return array<int|string>
+     */
+    public function getExcludedCategories(): array
+    {
+        return $this->excludedCategories;
+    }
+
+    /**
+     * Crea instancia desde JSON
+     */
+    public static function fromJson(string $json): self
+    {
+        $decoded = json_decode($json, true);
+
+        if (!is_array($decoded)) {
+            return self::empty();
+        }
+
+        return new self($decoded);
+    }
+
+    /**
+     * Crea instancia vacia
+     */
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+}

Shared/Domain/ValueObjects/ExclusionRule.php

@@ -0,0 +1,37 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\ValueObjects;
+
+/**
+ * Clase base abstracta para reglas de exclusion
+ *
+ * Define el contrato comun para todos los tipos de exclusion.
+ * Cada implementacion concreta define su logica de matching.
+ *
+ * @package ROITheme\Shared\Domain\ValueObjects
+ */
+abstract class ExclusionRule
+{
+    /**
+     * Evalua si el contexto actual coincide con la regla
+     *
+     * @param array<string, mixed> $context Contexto de la pagina actual
+     * @return bool True si el contexto coincide (debe excluirse)
+     */
+    abstract public function matches(array $context): bool;
+
+    /**
+     * Verifica si la regla tiene valores configurados
+     *
+     * @return bool True si hay valores configurados
+     */
+    abstract public function hasValues(): bool;
+
+    /**
+     * Serializa los valores para almacenamiento
+     *
+     * @return string JSON string
+     */
+    abstract public function serialize(): string;
+}

Shared/Domain/ValueObjects/ExclusionRuleSet.php

@@ -0,0 +1,100 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\ValueObjects;
+
+/**
+ * Value Object Compuesto: Conjunto de reglas de exclusion
+ *
+ * Agrupa todas las reglas de exclusion para un componente.
+ * Evalua con logica OR (si cualquier regla coincide, se excluye).
+ *
+ * @package ROITheme\Shared\Domain\ValueObjects
+ */
+final class ExclusionRuleSet
+{
+    public function __construct(
+        private readonly string $componentName,
+        private readonly bool $enabled,
+        private readonly CategoryExclusion $categoryExclusion,
+        private readonly PostIdExclusion $postIdExclusion,
+        private readonly UrlPatternExclusion $urlPatternExclusion
+    ) {}
+
+    /**
+     * Evalua si el componente debe excluirse segun el contexto actual
+     *
+     * @param array<string, mixed> $context Contexto de la pagina actual
+     * @return bool True si debe excluirse (NO mostrar)
+     */
+    public function shouldExclude(array $context): bool
+    {
+        if (!$this->enabled) {
+            return false;
+        }
+
+        // Evaluar cada tipo de exclusion (OR logico)
+        if ($this->categoryExclusion->matches($context)) {
+            return true;
+        }
+
+        if ($this->postIdExclusion->matches($context)) {
+            return true;
+        }
+
+        if ($this->urlPatternExclusion->matches($context)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Verifica si tiene alguna regla configurada
+     */
+    public function hasAnyRule(): bool
+    {
+        return $this->categoryExclusion->hasValues()
+            || $this->postIdExclusion->hasValues()
+            || $this->urlPatternExclusion->hasValues();
+    }
+
+    public function getComponentName(): string
+    {
+        return $this->componentName;
+    }
+
+    public function isEnabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function getCategoryExclusion(): CategoryExclusion
+    {
+        return $this->categoryExclusion;
+    }
+
+    public function getPostIdExclusion(): PostIdExclusion
+    {
+        return $this->postIdExclusion;
+    }
+
+    public function getUrlPatternExclusion(): UrlPatternExclusion
+    {
+        return $this->urlPatternExclusion;
+    }
+
+    /**
+     * Crea una instancia sin exclusiones (por defecto)
+     */
+    public static function empty(string $componentName): self
+    {
+        return new self(
+            $componentName,
+            false,
+            CategoryExclusion::empty(),
+            PostIdExclusion::empty(),
+            UrlPatternExclusion::empty()
+        );
+    }
+}

Shared/Domain/ValueObjects/PostIdExclusion.php

@@ -0,0 +1,86 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\ValueObjects;
+
+/**
+ * Value Object: Exclusion por ID de post/pagina
+ *
+ * Evalua si el post/pagina actual esta en la lista de IDs excluidos.
+ *
+ * @package ROITheme\Shared\Domain\ValueObjects
+ */
+final class PostIdExclusion extends ExclusionRule
+{
+    /**
+     * @param array<int> $excludedPostIds Lista de IDs de posts/paginas
+     */
+    public function __construct(
+        private readonly array $excludedPostIds = []
+    ) {}
+
+    /**
+     * {@inheritdoc}
+     *
+     * Contexto esperado:
+     * - post_id: int
+     */
+    public function matches(array $context): bool
+    {
+        if (!$this->hasValues()) {
+            return false;
+        }
+
+        $postId = $context['post_id'] ?? 0;
+
+        if ($postId === 0) {
+            return false;
+        }
+
+        return in_array($postId, $this->excludedPostIds, true);
+    }
+
+    public function hasValues(): bool
+    {
+        return !empty($this->excludedPostIds);
+    }
+
+    public function serialize(): string
+    {
+        return json_encode($this->excludedPostIds);
+    }
+
+    /**
+     * @return array<int>
+     */
+    public function getExcludedPostIds(): array
+    {
+        return $this->excludedPostIds;
+    }
+
+    /**
+     * Crea instancia desde JSON
+     */
+    public static function fromJson(string $json): self
+    {
+        $decoded = json_decode($json, true);
+
+        if (!is_array($decoded)) {
+            return self::empty();
+        }
+
+        // Asegurar que son enteros
+        $ids = array_map('intval', $decoded);
+        $ids = array_filter($ids, fn(int $id): bool => $id > 0);
+
+        return new self(array_values($ids));
+    }
+
+    /**
+     * Crea instancia vacia
+     */
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+}

Shared/Domain/ValueObjects/UrlPatternExclusion.php

@@ -0,0 +1,146 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Domain\ValueObjects;
+
+/**
+ * Value Object: Exclusion por patron URL
+ *
+ * Evalua si la URL actual coincide con alguno de los patrones configurados.
+ * Soporta:
+ * - Substring simple: "/privado/" coincide con cualquier URL que contenga ese texto
+ * - Regex: Patrones que empiezan y terminan con "/" son evaluados como regex
+ *
+ * @package ROITheme\Shared\Domain\ValueObjects
+ */
+final class UrlPatternExclusion extends ExclusionRule
+{
+    /**
+     * @param array<string> $urlPatterns Lista de patrones (substring o regex)
+     */
+    public function __construct(
+        private readonly array $urlPatterns = []
+    ) {}
+
+    /**
+     * {@inheritdoc}
+     *
+     * Contexto esperado:
+     * - request_uri: string (URI del request)
+     * - url: string (URL completa, opcional)
+     */
+    public function matches(array $context): bool
+    {
+        if (!$this->hasValues()) {
+            return false;
+        }
+
+        $requestUri = $context['request_uri'] ?? '';
+        $url = $context['url'] ?? '';
+
+        if ($requestUri === '' && $url === '') {
+            return false;
+        }
+
+        foreach ($this->urlPatterns as $pattern) {
+            if ($this->matchesPattern($pattern, $requestUri, $url)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Evalua si un patron coincide con el request_uri o url
+     */
+    private function matchesPattern(string $pattern, string $requestUri, string $url): bool
+    {
+        // Detectar si es regex (empieza con /)
+        if ($this->isRegex($pattern)) {
+            return $this->matchesRegex($pattern, $requestUri);
+        }
+
+        // Substring matching
+        return $this->matchesSubstring($pattern, $requestUri, $url);
+    }
+
+    /**
+     * Detecta si el patron es una expresion regular
+     */
+    private function isRegex(string $pattern): bool
+    {
+        // Un patron regex debe empezar con / y terminar con / (posiblemente con flags)
+        return preg_match('#^/.+/[gimsux]*$#', $pattern) === 1;
+    }
+
+    /**
+     * Evalua coincidencia regex
+     */
+    private function matchesRegex(string $pattern, string $subject): bool
+    {
+        // Suprimir warnings de regex invalidos
+        $result = @preg_match($pattern, $subject);
+
+        return $result === 1;
+    }
+
+    /**
+     * Evalua coincidencia por substring
+     */
+    private function matchesSubstring(string $pattern, string $requestUri, string $url): bool
+    {
+        if ($requestUri !== '' && str_contains($requestUri, $pattern)) {
+            return true;
+        }
+
+        if ($url !== '' && str_contains($url, $pattern)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    public function hasValues(): bool
+    {
+        return !empty($this->urlPatterns);
+    }
+
+    public function serialize(): string
+    {
+        return json_encode($this->urlPatterns, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+    }
+
+    /**
+     * @return array<string>
+     */
+    public function getUrlPatterns(): array
+    {
+        return $this->urlPatterns;
+    }
+
+    /**
+     * Crea instancia desde JSON
+     */
+    public static function fromJson(string $json): self
+    {
+        $decoded = json_decode($json, true);
+
+        if (!is_array($decoded)) {
+            return self::empty();
+        }
+
+        // Filtrar valores vacios
+        $patterns = array_filter($decoded, fn($p): bool => is_string($p) && $p !== '');
+
+        return new self(array_values($patterns));
+    }
+
+    /**
+     * Crea instancia vacia
+     */
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+}