package de.gecheckt.pdf.umbenenner.adapter.in.gui.editor;

import java.util.Objects;

/**
 * Represents a field-level validation finding that is displayed directly below the affected
 * input field in the GUI configuration editor.
 * <p>
 * Field-level findings complement the central message area: the central area shows all findings
 * in a consolidated list while this type carries the finding directly to the specific field it
 * relates to, making it easier for the user to identify and correct the problem.
 * <p>
 * The {@code fieldKey} uses the property key as defined in the {@code .properties} file
 * (e.g., {@code "source.folder"}, {@code "ai.provider.openai-compatible.apiKey"}).
 * Using the property key as the field identifier keeps the validation model stable and independent
 * of GUI layout changes.
 * <p>
 * Field-level findings are always rendered as small red German-language text directly beneath
 * the affected control. Findings with severity {@link GuiMessageSeverity#INFO} or
 * {@link GuiMessageSeverity#HINT} may also be shown field-near when the context is helpful.
 * <p>
 * This record contains no JavaFX references and is safe to create on any thread.
 *
 * @param fieldKey the property key identifying the affected configuration field; never {@code null}
 * @param severity the severity of this finding; never {@code null}
 * @param text     short, German-language description of the problem; never {@code null}
 */
public record GuiFieldFinding(
        String fieldKey,
        GuiMessageSeverity severity,
        String text) {

    /**
     * Creates a new field-level finding.
     *
     * @param fieldKey property key of the affected field; must not be {@code null}
     * @param severity severity of the finding; must not be {@code null}
     * @param text     German-language problem description; must not be {@code null}
     * @throws NullPointerException if any parameter is {@code null}
     */
    public GuiFieldFinding {
        Objects.requireNonNull(fieldKey, "fieldKey must not be null");
        Objects.requireNonNull(severity, "severity must not be null");
        Objects.requireNonNull(text, "text must not be null");
    }

    /**
     * Creates an error-severity field finding.
     *
     * @param fieldKey property key of the affected field; must not be {@code null}
     * @param text     German-language problem description; must not be {@code null}
     * @return a new finding with severity {@link GuiMessageSeverity#ERROR}
     */
    public static GuiFieldFinding error(String fieldKey, String text) {
        return new GuiFieldFinding(fieldKey, GuiMessageSeverity.ERROR, text);
    }

    /**
     * Creates a warning-severity field finding.
     *
     * @param fieldKey property key of the affected field; must not be {@code null}
     * @param text     German-language problem description; must not be {@code null}
     * @return a new finding with severity {@link GuiMessageSeverity#WARNING}
     */
    public static GuiFieldFinding warning(String fieldKey, String text) {
        return new GuiFieldFinding(fieldKey, GuiMessageSeverity.WARNING, text);
    }
}
