<?php

declare(strict_types=1);

namespace Builder\Core\Foundation\Settings;

use Builder\Core\Foundation\Definition\FieldBuilder;

/**
 * Abstract base for settings extensions.
 *
 * Allows third-party code to contribute extra sections and fields to an
 * existing settings page, stored in a separate settings class.
 *
 * Usage:
 *   class HomepageSettingsExtension extends SettingsExtension {
 *       public static function getExtends(): string { return GeneralSettings::class; }
 *       public static function getSettingsClass(): string { return HomepageSettings::class; }
 *       public function fields(): FieldBuilder { ... }
 *       public function rules(): array { ... }
 *   }
 *
 *   // In a service provider:
 *   $registry->extendSettings(HomepageSettingsExtension::class);
 */
abstract class SettingsExtension
{
    /**
     * The settings page class this extension adds sections to (UI target).
     *
     * @return class-string<BuilderSettings>
     */
    abstract public static function getExtends(): string;

    /**
     * The settings class that stores data for the contributed fields.
     *
     * @return class-string<BuilderSettings>
     */
    abstract public static function getSettingsClass(): string;

    /**
     * Fields and sections to inject into the target settings page.
     */
    public function fields(): FieldBuilder
    {
        return FieldBuilder::make();
    }

    /**
     * Validation rules for the contributed fields.
     *
     * @return array<string, mixed>
     */
    public function rules(): array
    {
        return [];
    }
}
