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

/**
 * Describes the origin of the currently displayed model value in the GUI model selection area.
 * <p>
 * The GUI uses this enum to decide which control to show for the model input:
 * <ul>
 *   <li>When the source is {@link #LIST_REMOTE_SUCCESS}, a non-editable {@code ComboBox}
 *       is shown, pre-populated with the remote list.</li>
 *   <li>When the source is {@link #LIST_UNAVAILABLE_MANUAL_INPUT} or
 *       {@link #LIST_FAILED_MANUAL_INPUT}, a plain text input field is shown instead,
 *       allowing the user to enter the model name manually.</li>
 *   <li>{@link #NOT_YET_LOADED} represents the initial state before the first retrieval
 *       attempt; the GUI should render a loading indicator or show the text field
 *       in a disabled/pending state.</li>
 * </ul>
 * <p>
 * This enum is intentionally free of JavaFX references so it can be used in unit-tested
 * view-model code without starting a JavaFX runtime.
 */
public enum GuiModelSource {

    /**
     * The model list was successfully retrieved from the remote provider endpoint.
     * <p>
     * A non-editable {@code ComboBox} is displayed, pre-selecting the first available model.
     */
    LIST_REMOTE_SUCCESS,

    /**
     * No model list is available because the provider does not expose a model catalogue endpoint
     * or because the configuration was incomplete.
     * <p>
     * A manual text input field is shown and the user must enter the model identifier by hand.
     */
    LIST_UNAVAILABLE_MANUAL_INPUT,

    /**
     * A technical error occurred while retrieving the model list (e.g., HTTP error, timeout,
     * authentication failure).
     * <p>
     * A manual text input field is shown so the user can still supply a model name; the GUI
     * also reports the failure in the central message area.
     */
    LIST_FAILED_MANUAL_INPUT,

    /**
     * The initial state before the first model retrieval attempt has been made.
     * <p>
     * The GUI should indicate that a retrieval is pending and must not present the manual
     * input field as the definitive fallback until at least one retrieval attempt has completed.
     */
    NOT_YET_LOADED
}
