<?php
declare(strict_types=1);

namespace Help4BuilderSuite\Support;

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

final class ImageInputGuidance
{
    /**
     * @return array<string, array<string, mixed>>
     */
    public static function profiles(): array
    {
        $profiles = [
            'content' => self::profile(
                __('Content image', 'help4-builder-suite'),
                1600,
                900,
                '16:9',
                300,
                __('Use for page sections, articles, and general visual content. Keep the important subject inside the center safe area.', 'help4-builder-suite')
            ),
            'hero' => self::profile(
                __('Hero or banner', 'help4-builder-suite'),
                1920,
                1080,
                '16:9',
                450,
                __('Use a wide source with room for text and test the crop on desktop, tablet, and mobile. Set the focal position on the real subject.', 'help4-builder-suite')
            ),
            'background' => self::profile(
                __('Section background', 'help4-builder-suite'),
                1920,
                1080,
                '16:9',
                400,
                __('Backgrounds usually crop. Avoid text inside the image and keep faces, products, and logos away from the outer edges.', 'help4-builder-suite')
            ),
            'slider' => self::profile(
                __('Slider background', 'help4-builder-suite'),
                1920,
                1080,
                '16:9',
                450,
                __('Keep every slide at the same ratio to prevent layout movement. Check focal position and layer contrast at every device preset.', 'help4-builder-suite')
            ),
            'video_poster' => self::profile(
                __('Video poster or failure image', 'help4-builder-suite'),
                1920,
                1080,
                '16:9',
                350,
                __('Match the player ratio exactly so the poster, first frame, and failure state do not jump or crop differently.', 'help4-builder-suite')
            ),
            'social' => self::profile(
                __('Social sharing image', 'help4-builder-suite'),
                1200,
                630,
                '1.91:1',
                300,
                __('Keep the main subject and any short text inside the center area so link previews remain readable after social-platform cropping.', 'help4-builder-suite')
            ),
            'logo' => self::profile(
                __('Logo or wordmark', 'help4-builder-suite'),
                512,
                0,
                __('Original ratio', 'help4-builder-suite'),
                150,
                __('Use the approved original. SVG is preferred for trusted vector logos; otherwise use transparent WebP or PNG and never stretch the proportions.', 'help4-builder-suite'),
                ['svg', 'webp', 'png']
            ),
            'site_icon' => self::profile(
                __('Site icon or favicon', 'help4-builder-suite'),
                512,
                512,
                '1:1',
                100,
                __('Use a simple square mark with clear edges and no tiny text. WordPress creates the smaller browser and device sizes.', 'help4-builder-suite'),
                ['png', 'webp']
            ),
            'portrait' => self::profile(
                __('Staff portrait or headshot', 'help4-builder-suite'),
                1200,
                1500,
                '4:5',
                350,
                __('Use consistent lighting and framing. Leave space around the face, then set the focal point so desktop and mobile crops remain respectful.', 'help4-builder-suite')
            ),
            'product' => self::profile(
                __('Product image', 'help4-builder-suite'),
                1600,
                1600,
                '1:1',
                400,
                __('Use the same canvas and background treatment across a product set. Keep the complete product visible and leave breathing room around it.', 'help4-builder-suite')
            ),
            'gallery' => self::profile(
                __('Gallery images', 'help4-builder-suite'),
                1600,
                1200,
                '4:3',
                350,
                __('A consistent ratio makes the gallery feel intentional. Mixed ratios are fine only when the selected gallery layout is designed for them.', 'help4-builder-suite')
            ),
            'event' => self::profile(
                __('Event or program artwork', 'help4-builder-suite'),
                1600,
                900,
                '16:9',
                350,
                __('Keep event details in editable text, not only in the artwork. Use a clear subject and verify the card crop on mobile.', 'help4-builder-suite')
            ),
            'email' => self::profile(
                __('Email campaign image', 'help4-builder-suite'),
                1200,
                600,
                '2:1',
                250,
                __('Keep essential meaning in the email text because many inboxes block images. Use a lightweight image that stays legible on a phone.', 'help4-builder-suite')
            ),
            'screenshot' => self::profile(
                __('Website or interface screenshot', 'help4-builder-suite'),
                1600,
                1000,
                '8:5',
                450,
                __('Capture the real interface at a readable scale. Avoid stretching, preserve the source ratio, and remove private information before upload.', 'help4-builder-suite')
            ),
        ];

        /**
         * Filters the image-guidance profiles available across Help4 admin screens.
         *
         * Each profile accepts label, width, height, ratio, max_kb, formats, and advice.
         *
         * @param array<string, array<string, mixed>> $profiles
         */
        $profiles = apply_filters('h4bs_image_guidance_profiles', $profiles);
        if (! is_array($profiles)) {
            return [];
        }

        $clean = [];
        foreach ($profiles as $slug => $profile) {
            $slug = sanitize_key((string) $slug);
            if ($slug === '' || ! is_array($profile)) {
                continue;
            }

            $formats = [];
            foreach ((array) ($profile['formats'] ?? []) as $format) {
                $format = sanitize_key((string) $format);
                if ($format !== '') {
                    $formats[] = $format;
                }
            }

            $clean[$slug] = [
                'label' => sanitize_text_field((string) ($profile['label'] ?? $slug)),
                'width' => max(0, absint($profile['width'] ?? 0)),
                'height' => max(0, absint($profile['height'] ?? 0)),
                'ratio' => sanitize_text_field((string) ($profile['ratio'] ?? '')),
                'max_kb' => max(0, absint($profile['max_kb'] ?? 0)),
                'formats' => array_values(array_unique($formats)),
                'advice' => sanitize_text_field((string) ($profile['advice'] ?? '')),
            ];
        }

        return $clean;
    }

    /**
     * @return array<string, mixed>
     */
    public static function clientConfig(): array
    {
        return [
            'profiles' => self::profiles(),
            'defaultProfile' => 'content',
            'docsUrl' => 'https://help4wordpress.com/help4-builder-images-media/',
            'labels' => [
                'title' => __('Best image size', 'help4-builder-suite'),
                'purpose' => __('Image use', 'help4-builder-suite'),
                'recommended' => __('Recommended', 'help4-builder-suite'),
                'formats' => __('Best formats', 'help4-builder-suite'),
                'weight' => __('Target file weight', 'help4-builder-suite'),
                'selected' => __('Selected image', 'help4-builder-suite'),
                'none' => __('No image selected yet.', 'help4-builder-suite'),
                'checking' => __('Checking image dimensions...', 'help4-builder-suite'),
                'good' => __('Good fit for this use.', 'help4-builder-suite'),
                'small' => __('This image is smaller than the recommended source size and may look soft on larger screens.', 'help4-builder-suite'),
                'ratio' => __('This image uses a different aspect ratio, so review its crop at every device size.', 'help4-builder-suite'),
                'format' => __('This file format is not preferred for this use. WebP or AVIF is usually best for photos.', 'help4-builder-suite'),
                'mixed' => __('The selected gallery uses mixed aspect ratios. Confirm the layout is intended to crop or vary.', 'help4-builder-suite'),
                'unavailable' => __('Dimensions could not be read. Open the Media Library item and verify its pixel size before publishing.', 'help4-builder-suite'),
                'openGuide' => __('Open the complete image guide', 'help4-builder-suite'),
            ],
        ];
    }

    /**
     * @param array<int, string> $formats
     * @return array<string, mixed>
     */
    private static function profile(
        string $label,
        int $width,
        int $height,
        string $ratio,
        int $maxKb,
        string $advice,
        array $formats = ['avif', 'webp', 'jpg', 'jpeg', 'png']
    ): array {
        return [
            'label' => $label,
            'width' => $width,
            'height' => $height,
            'ratio' => $ratio,
            'max_kb' => $maxKb,
            'formats' => $formats,
            'advice' => $advice,
        ];
    }
}
