<?php

namespace SugarCalendarBookings\Migration;

/**
 * Migration UI Config Interface.
 *
 * Defines the UI configuration contract for migration sources that want
 * to display a migration modal in the admin interface.
 *
 * Separates UI/presentation concerns from data migration concerns
 * (which are handled by SourceAdapterInterface).
 *
 * @since 1.3.0
 */
interface MigrationUIConfigInterface {

	/**
	 * Get the source adapter ID this UI config is for.
	 *
	 * Must match the ID returned by the corresponding SourceAdapterInterface::get_id().
	 *
	 * @since 1.3.0
	 *
	 * @return string
	 */
	public function get_source_id(): string;

	/**
	 * Get the display name for this migration source.
	 *
	 * @since 1.3.0
	 *
	 * @return string
	 */
	public function get_source_name(): string;

	/**
	 * Check if this migration source is available.
	 *
	 * Should return true if the source plugin is active and has data to migrate.
	 *
	 * @since 1.3.0
	 *
	 * @return bool
	 */
	public function is_available(): bool;

	/**
	 * Get modal configuration for this migration source.
	 *
	 * Returns an array with the following structure:
	 * - header: array{
	 *     source_icon: string,
	 *     source_icon_alt: string,
	 *     title: string,
	 *     description?: string,
	 *   }
	 * - options: array<array{
	 *     value: string,
	 *     label: string,
	 *     description: string,
	 *     is_default?: bool,
	 *     advanced_options?: array<array{
	 *       name: string,
	 *       label: string,
	 *       entity_type: string,
	 *       checked?: bool,
	 *       disabled?: bool,
	 *       info_message?: string,
	 *     }>,
	 *   }>
	 * - info_message?: string
	 * - entity_labels: array<string, string>
	 * - i18n: array{
	 *     confirm_button: string,
	 *     cancel_button: string,
	 *     complete_title: string,
	 *     complete_description: string,
	 *   }
	 *
	 * @since 1.3.0
	 *
	 * @return array<string, mixed>
	 */
	public function get_modal_config(): array;
}
