<?php

namespace Formatrica\Frontend;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Form-level rendering extension point (docs/wporg-free-runtime-separation.md
 * §6.4). The Free Form_Renderer produces a complete linear Free form and asks
 * the registered extension to decorate it with paid form-level behavior:
 * multi-step assembly, conditional-logic data attributes, custom field
 * attributes, a custom wrapper class, and the Save & Resume draft control.
 *
 * A Free package registers no extension (Null_Form_Render_Extension is the
 * default), so none of these decorations are emitted. The Pro package registers
 * Pro_Form_Render_Extension.
 */
interface Form_Render_Extension_Interface
{
    /**
     * Decorate a single field's markup — conditional-logic data attribute and
     * custom HTML attributes.
     *
     * @param array<string, mixed> $field
     * @param array<string, string> $field_name_by_key key => submission name map
     */
    public function decorate_field(string $markup, array $field, array $field_name_by_key): string;

    /**
     * Extra class token(s) for the form wrapper beyond the base "formatrica"
     * (custom wrapper class). Returns '' when none.
     *
     * @param array<string, mixed> $options
     */
    public function wrapper_class(array $options): string;

    /**
     * Assemble step buckets into multi-step markup, or return null to let the
     * core render the form linearly (Free fallback: ignore step breaks).
     *
     * @param list<list<string>>          $steps
     * @param list<array<string, string>> $step_meta
     */
    public function render_steps(array $steps, array $step_meta): ?string;

    /**
     * Save & Resume draft button markup, or '' when the form has no draft
     * control (Free fallback: no button).
     *
     * @param array<string, mixed> $options
     * @param array<int, array<string, mixed>> $fields
     */
    public function draft_button(array $options, array $fields): string;
}
