<?php

declare(strict_types=1);

namespace Builder\Core\Foundation\Contracts\Modules;

/**
 * Contract for the blocks package's field handler.
 *
 * Extends FieldHandler with validation capabilities for block editor data.
 * Register with: app(FieldHandlerRegistry::class)->register(FieldComponent::BlockEditor->value, BlockFieldHandler::class)
 */
interface BlockFieldHandler extends FieldHandler
{
    /**
     * Generate Laravel validation rules for the block fields in the request.
     * Returns a flat array of dot-notation rules, e.g. "content.0.data.title" => ["required"].
     *
     * @param  array<string, array<string, mixed>>  $blockFields  field name => field definition
     * @param  array<string, mixed>  $requestData
     * @return array<string, list<string>>
     */
    public function rulesFor(array $blockFields, array $requestData): array;

    /**
     * Generate human-readable attribute names for block validation error messages.
     * Maps dot-notation paths like "content.0.data.title" to the field's display label.
     *
     * @param  array<string, array<string, mixed>>  $blockFields  field name => field definition
     * @param  array<string, mixed>  $requestData
     * @return array<string, string>
     */
    public function attributesFor(array $blockFields, array $requestData): array;
}
