<?php
/**
 * ITSWEBER CMS – Abstract Section Base Class
 *
 * Base class for all page builder sections. Every section type
 * (core or plugin-provided) extends this class and implements
 * its metadata, data validation and default values.
 *
 * @author    Benny Weber (ITSWEBER)
 * @copyright © ITSWEBER – www.itsweber.de
 * @contact   kontakt@itsweber.de
 */

namespace App\Sections;

use App\Core\Request;

abstract class AbstractSection
{
    /* ── Metadaten ──────────────────────────────────────── */
    abstract public static function typeKey(): string;
    abstract public static function label(): string;
    abstract public static function category(): string;

    public static function allowMultiple(): bool  { return true; }
    public static function description(): string  { return ''; }

    /**
     * Theme binding: return theme slug if section is theme-exclusive.
     * Null = universal (available in all themes, default for core/extended).
     * Theme-bound sections are only visible when their theme is active.
     */
    public static function themeSlug(): ?string { return null; }

    /**
     * SVG-Icon für das "Section hinzufügen" Modal.
     * Inline-SVG String, kein Emoji, kein Icon-Font.
     */
    public static function iconSvg(): string { return ''; }

    /* ── Datenvalidierung ───────────────────────────────── */
    abstract public function buildData(Request $request): array;

    /** Default-Daten wenn eine neue Instanz erstellt wird */
    public function defaultData(): array { return []; }

    /* ── Admin-Form ─────────────────────────────────────── */

    /**
     * Pfad zur Admin-Form-View (relativ zu admin/views/).
     * Kann von Themes überschrieben werden.
     */
    public function adminFormView(): string
    {
        return 'sections/' . static::typeKey();
    }

    /* ── Plugin Template Paths ─────────────────────────── */

    /**
     * Base path for admin form view, relative to CMS root.
     * Core sections return null → default lookup (admin/views/sections/).
     * Plugin sections override, e.g. 'plugins/aurora-background/views/admin'.
     */
    public function adminFormBasePath(): ?string { return null; }

    /**
     * Base path for frontend template, relative to CMS root.
     * Core sections return null → default lookup (themes/).
     * Plugin sections override, e.g. 'plugins/aurora-background/views/frontend'.
     */
    public function frontendTemplatePath(): ?string { return null; }

    /* ── Frontend-Assets (nur laden wenn Section aktiv) ── */
    public function styles(): array  { return []; }
    public function scripts(): array { return []; }

    /* ── Shared Helpers ─────────────────────────────────── */

    /**
     * Whitelist-basierte Token-Validierung.
     * Gibt den Wert zurück wenn er in der erlaubten Liste ist, sonst ''.
     */
    protected static function sanitizeToken(string $value, array $allowed): string
    {
        return in_array($value, $allowed, true) ? $value : '';
    }

    /**
     * Sanitize a CSS color value (hex only, or empty).
     */
    protected static function sanitizeColor(string $value): string
    {
        if ($value === '') return '';
        return preg_match('/^#[0-9a-fA-F]{3,8}$/', $value) ? $value : '';
    }

    /** Standard-Whitelist: Farbschema */
    protected static function allowedColorScheme(): array
    {
        return ['', 'alt', 'primary', 'dark', 'none'];
    }

    /** Standard-Whitelist: Text-Ausrichtung */
    protected static function allowedSectionAlign(): array
    {
        return ['', 'left'];
    }

    /** Standard-Whitelist: Karten-Stil */
    protected static function allowedCardStyle(): array
    {
        return ['', 'bordered', 'flat'];
    }

    /** Standard-Whitelist: Section-Textfarbe */
    protected static function allowedSectionTextColor(): array
    {
        return ['', 'black', 'white', 'theme'];
    }

    /** Standard-Whitelist: Spaltenanzahl */
    protected static function allowedColumns(): array
    {
        return ['', '2', '3', '4'];
    }

    /** Standard-Whitelist: Overlay-Stärke */
    protected static function allowedOverlay(): array
    {
        return ['', 'light', 'medium', 'heavy'];
    }

    /** Standard-Whitelist: Maximale Breite */
    protected static function allowedMaxWidth(): array
    {
        return ['', 'sm', 'md', 'lg'];
    }

    /**
     * Merge theme-specific extra data (premium tokens).
     * Extra fields can only ADD new keys – cannot override core fields.
     */
    protected function mergeThemeExtras(array $data, Request $request): array
    {
        $extra = theme_section_extra_data(static::typeKey(), $request);
        if ($extra) {
            foreach ($extra as $k => $v) {
                if (!array_key_exists($k, $data)) {
                    $data[$k] = $v;
                }
            }
        }
        return $data;
    }
}
