<?php

declare(strict_types=1);

namespace Builder\Core\Foundation\Contracts\Modules;

use Illuminate\Database\Eloquent\Model;

/**
 * Base contract for module-provided field handlers.
 *
 * Implement this interface to handle loading and persisting field data that is
 * stored outside the main model table (e.g. a blocks table, media attachments).
 * Register the implementation with FieldHandlerRegistry in your service provider.
 */
interface FieldHandler
{
    /**
     * Load field values from external storage into the record's attribute bag.
     *
     * @param  array<string, array<string, mixed>>  $fields  field name => field definition
     */
    public function loadFields(Model $record, array $fields, ?string $locale = null): void;

    /**
     * Persist field values from the request into external storage after save.
     *
     * @param  array<string, array<string, mixed>>  $fields
     * @param  array<string, mixed>  $requestData
     */
    public function syncFields(Model $record, array $fields, array $requestData, ?string $locale = null): void;
}
