<?php

/**
 * JCOGS Image Pro - Field Provider Interface
 * Provider Architecture Foundation
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      Provider Architecture v1.0
 */

namespace JCOGSDesign\JCOGSImagePro\Service\Provider;

/**
 * Field Provider Interface
 * 
 * Allows companion add-ons to register custom field type implementations
 * that integrate with EE's native Files field type.
 * 
 * This is a STUB interface for future development. It will be fully
 * implemented when the first field provider companion add-on is developed.
 * 
 * Planned features:
 * - EXIF data reading/writing
 * - Interactive cropping during save
 * - Preset selection for automatic processing
 * - Manual focal point selection
 * - Batch preset application
 * 
 * Companion add-ons can implement this interface and register their
 * providers via the 'jcogs_img_pro_register_providers' extension hook.
 * 
 * @todo Finalize interface methods when field provider add-on development begins
 */
interface FieldProviderInterface
{
    /**
     * Get provider name for identification
     * 
     * @return string Provider identifier (e.g., 'enhanced_file_field', 'exif_field')
     */
    public function getName(): string;
    
    /**
     * Check if provider is available
     * 
     * Should verify required dependencies are present.
     * 
     * IMPORTANT: Must NOT throw exceptions. Return false on any error.
     * 
     * @return bool True if provider can be used
     */
    public function isAvailable(): bool;
    
    /**
     * Get available field features
     * 
     * @return array Feature flags:
     *   [
     *     'exif_read' => bool,      // Read EXIF data from images
     *     'exif_write' => bool,     // Write EXIF data to images
     *     'interactive_crop' => bool, // Interactive cropping UI
     *     'preset_selection' => bool, // Preset selector interface
     *     'focal_point' => bool,     // Manual focal point selection
     *     'batch_presets' => bool,   // Apply presets to multiple images
     *   ]
     */
    public function getFeatures(): array;
    
    // Additional methods to be defined during implementation:
    // - processFieldData(array $fieldData): array
    // - renderFieldControls(array $fieldData, array $fieldSettings): string
    // - getJavaScriptUrls(): array
    // - getCssUrls(): array
}
