<?php

namespace Kitgenix\PDF_Invoicing\Modules\Settings;

use Kitgenix\PDF_Invoicing\Core\ModuleInterface;
use Kitgenix\PDF_Invoicing\Modules\Email\EmailModule;
use Kitgenix\PDF_Invoicing\Modules\Invoicing\DocumentDisplay;
use Kitgenix\PDF_Invoicing\Modules\Invoicing\DocumentTypes;
use Kitgenix\PDF_Invoicing\Modules\Settings\SettingsTransfer;
use Kitgenix\PDF_Invoicing\Modules\Settings\SystemStatus;

defined( 'ABSPATH' ) || exit;

class SettingsModule implements ModuleInterface {

    /**
     * Hook suffix returned by add_submenu_page(), used to scope admin asset loading.
     *
     * @var string
     */
    private $page_hook = '';

    private ?EmailModule $email_module = null;

    public function __construct( ?EmailModule $email_module = null ) {
        $this->email_module = $email_module;
    }

    public function get_id(): string {
        return 'settings';
    }

    public function register(): void {
        if ( is_admin() ) {
            add_action( 'admin_menu', [ $this, 'add_menu_page' ] );
            add_action( 'admin_init', [ $this, 'register_settings' ] );
            add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_assets' ] );
            add_action( 'admin_notices', [ $this, 'render_admin_notices' ] );
            add_action( 'admin_post_kitgenix_pdf_invoicing_clear_event_log', [ $this, 'handle_clear_event_log' ] );
            add_action( 'admin_post_kitgenix_pdf_invoicing_export_settings', [ $this, 'handle_export_settings' ] );
            add_action( 'admin_post_kitgenix_pdf_invoicing_import_settings', [ $this, 'handle_import_settings' ] );
            add_action( 'admin_post_kitgenix_pdf_invoicing_upload_font', [ $this, 'handle_upload_font' ] );
            add_action( 'admin_post_kitgenix_pdf_invoicing_delete_font', [ $this, 'handle_delete_font' ] );
            add_action( 'update_option_' . Settings::OPTION_KEY, [ $this, 'on_settings_saved' ], 10, 3 );
        }
    }

    private function is_settings_screen_now(): bool {
        if ( function_exists( 'get_current_screen' ) ) {
            $screen = get_current_screen();
            if ( $screen ) {
                if ( $this->page_hook && $screen->id === $this->page_hook ) {
                    return true;
                }
                if ( ! $this->page_hook && $screen->id === 'kitgenix_page_kitgenix-pdf-invoicing-settings' ) {
                    return true;
                }
            }
        }

        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only gating for notice placement; capability check happens before this method is used. */
        $page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
        return ( $page === 'kitgenix-pdf-invoicing-settings' );
    }

    public function render_admin_notices(): void {
        if ( ! current_user_can( 'manage_woocommerce' ) ) {
            return;
        }

        if ( ! $this->is_settings_screen_now() ) {
            return;
        }

        if ( function_exists( 'settings_errors' ) ) {
            settings_errors();
        }
    }

    public function add_menu_page(): void {
        if ( function_exists( '\\kitgenix_ensure_admin_menu' ) ) {
            \kitgenix_ensure_admin_menu();
        }

        $this->page_hook = (string) add_submenu_page(
            'kitgenix',
            __( 'PDF Invoicing Settings', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            __( 'PDF Invoicing', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'manage_woocommerce',
            'kitgenix-pdf-invoicing-settings',
            [ $this, 'render_settings_page' ]
        );
    }

    public function enqueue_assets( string $hook_suffix ): void {
        // Primary check via hook suffix, with a GET-based fallback for some WP setups.
        if ( $this->page_hook && $hook_suffix !== $this->page_hook ) {
            // Only allow reading URL params for authorized users – this is
            // a non-actionable UI helper, not form processing.
            if ( ! current_user_can( 'manage_woocommerce' ) ) {
                return;
            }

            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- non-actionable UI helper; capability check above ensures only admins can read this. */
            $page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
            if ( ! $page || 'kitgenix-pdf-invoicing-settings' !== $page ) {
                return;
            }

        } elseif ( ! $this->page_hook && 'kitgenix_page_kitgenix-pdf-invoicing-settings' !== $hook_suffix ) {
            // Only allow reading URL params for authorized users – this is
            // a non-actionable UI helper, not form processing. Checking
            // capabilities here satisfies security scanners that warn when
            // superglobals are read without nonce verification.
            if ( ! current_user_can( 'manage_woocommerce' ) ) {
                return;
            }

            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- non-actionable UI helper; capability check above ensures only admins can read this. */
            $page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
            if ( ! $page || 'kitgenix-pdf-invoicing-settings' !== $page ) {
                return;
            }
        }

        wp_enqueue_media();

        if ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL' ) ) {
            $base_url = KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL;
        } elseif ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_FILE' ) ) {
            $base_url = plugin_dir_url( KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_FILE );
        } else {
            $base_url = plugin_dir_url( __FILE__ );
        }

        if ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_DIR' ) ) {
            $base_dir = KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_DIR;
        } elseif ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_FILE' ) ) {
            $base_dir = plugin_dir_path( KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_FILE );
        } else {
            $base_dir = plugin_dir_path( dirname( __DIR__, 3 ) . '/kitgenix-pdf-invoicing-for-woocommerce.php' );
        }

        $version = defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_VERSION' ) ? KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_VERSION : '1.0.5';
        $logo_media_js_file = trailingslashit( $base_dir ) . 'assets/js/admin-logo-media.js';
        $admin_css_file = trailingslashit( $base_dir ) . 'assets/css/admin.css';
        $tabs_js_file = trailingslashit( $base_dir ) . 'assets/js/kitgenix-admin-tabs.js';
        $components_js_file = trailingslashit( $base_dir ) . 'assets/js/kitgenix-admin-components.js';
        $settings_js_file = trailingslashit( $base_dir ) . 'assets/js/admin-settings.js';
        $logo_media_js_ver = file_exists( $logo_media_js_file ) ? (string) filemtime( $logo_media_js_file ) : $version;
        $admin_css_ver = file_exists( $admin_css_file ) ? (string) filemtime( $admin_css_file ) : $version;
        $tabs_js_ver = file_exists( $tabs_js_file ) ? (string) filemtime( $tabs_js_file ) : $version;
        $components_js_ver = file_exists( $components_js_file ) ? (string) filemtime( $components_js_file ) : $version;
        $settings_js_ver = file_exists( $settings_js_file ) ? (string) filemtime( $settings_js_file ) : $version;

        $handle = 'kitgenix-pdf-invoicing-admin-logo-media';

        wp_enqueue_script(
            $handle,
            $base_url . 'assets/js/admin-logo-media.js',
            [ 'media-editor', 'media-upload' ],
            $logo_media_js_ver,
            true
        );

        // Color picker + custom admin styles for a modern settings UI.
        wp_enqueue_style( 'wp-color-picker' );

        wp_enqueue_style( 'kitgenix-pdf-invoicing-for-woocommerce-admin-ui' );

        wp_enqueue_style(
            'kitgenix-pdf-invoicing-admin-settings',
            $base_url . 'assets/css/admin.css',
            [ 'kitgenix-pdf-invoicing-for-woocommerce-admin-ui' ],
            $admin_css_ver
        );

        wp_enqueue_script(
            'kitgenix-admin-tabs',
            $base_url . 'assets/js/kitgenix-admin-tabs.js',
            [],
            $tabs_js_ver,
            true
        );

        wp_enqueue_script(
            'kitgenix-admin-components',
            $base_url . 'assets/js/kitgenix-admin-components.js',
            [],
            $components_js_ver,
            true
        );

        wp_enqueue_script(
            'kitgenix-pdf-invoicing-admin-settings',
            $base_url . 'assets/js/admin-settings.js',
            [ 'wp-color-picker', 'jquery' ],
            $settings_js_ver,
            true
        );

    }

    public function register_settings(): void {
        register_setting(
            'kitgenix_pdf_invoicing_for_woocommerce_',
            Settings::OPTION_KEY,
            [
                'type'              => 'array',
                'sanitize_callback' => [ $this, 'sanitize_settings' ],
                'default'           => Settings::get_all(),
            ]
        );

        // Section 1: Company & document details.
        add_settings_section(
            'kitgenix_pdf_invoicing_main',
            __( 'Company & Document Details', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Configure the company details, logo, and basic invoice document settings.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        // Section 1b: Brand & styling options.
        add_settings_section(
            'kitgenix_pdf_invoicing_brand',
            __( 'Brand & Styling', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Adjust the colors used in your PDF documents so they match your store branding.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        add_settings_section(
            'kitgenix_pdf_invoicing_designer',
            __( 'Visual Template Designer', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Shape the bundled PDF layouts with no-code controls for alignment, spacing, panels, tables, totals, and footer presentation.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        add_settings_section(
            'kitgenix_pdf_invoicing_numbering',
            __( 'Numbering & Compliance', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Control prefixes, token-based numbering rules, reset periods, and fiscal-year aware sequences for issued documents.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        add_settings_section(
            'kitgenix_pdf_invoicing_localization',
            __( 'Localization, Tax & Legal Formatting', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Apply preset legal-formatting packs for cross-border stores, choose inclusive or exclusive tax presentation, set a document date format, and override tax terminology without editing templates.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        add_settings_section(
            'kitgenix_pdf_invoicing_fields',
            __( 'Field & Line-Item Controls', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Choose which order fields, fulfilment references, notes, and line-item details are rendered on your PDF documents.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        add_settings_section(
            'kitgenix_pdf_invoicing_document_rules',
            __( 'Document Generation Rules', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Decide which documents are available, which order statuses they apply to, and whether they require a paid or unpaid order state.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        // Section 2: Email attachments.
        add_settings_section(
            'kitgenix_pdf_invoicing_email',
            __( 'Email Attachments', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            function () {
                echo '<p>' . esc_html__( 'Choose which PDF documents to attach to specific WooCommerce emails.', 'kitgenix-pdf-invoicing-for-woocommerce' ) . '</p>';
            },
            'kitgenix-pdf-invoicing-settings'
        );

        // Fields for section 1.
        $this->add_field(
            'company_name',
            __( 'Company name', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_company_name' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'company_address',
            __( 'Company address', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_company_address' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'company_email',
            __( 'Company email', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_company_email' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'company_phone',
            __( 'Company phone', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_company_phone' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'tax_id',
            __( 'Tax / VAT ID', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_tax_id' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'invoice_prefix',
            __( 'Invoice prefix', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_invoice_prefix' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'receipt_prefix',
            __( 'Receipt prefix', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_receipt_prefix' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'credit_note_prefix',
            __( 'Credit note prefix', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_credit_note_prefix' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'packing_slip_prefix',
            __( 'Packing slip prefix', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_packing_slip_prefix' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'invoice_number_format',
            __( 'Invoice number format', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_invoice_number_format' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'receipt_number_format',
            __( 'Receipt number format', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_receipt_number_format' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'packing_slip_number_format',
            __( 'Packing slip number format', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_packing_slip_number_format' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'credit_note_number_format',
            __( 'Credit note number format', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_credit_note_number_format' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'number_sequence_reset',
            __( 'Sequence reset period', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_number_sequence_reset' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'number_sequence_padding',
            __( 'Sequence padding', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_number_sequence_padding' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'fiscal_year_start_month',
            __( 'Fiscal year start month', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_fiscal_year_start_month' ],
            'kitgenix_pdf_invoicing_numbering'
        );

        $this->add_field(
            'localization_pack',
            __( 'Localization pack', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_localization_pack' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'tax_display_mode',
            __( 'Tax display mode', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_tax_display_mode' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'document_date_format',
            __( 'Document date format', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_document_date_format' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'show_currency_code',
            __( 'Show ISO currency code', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_currency_code' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'tax_label_override',
            __( 'Tax label override', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_tax_label_override' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'tax_registration_label_override',
            __( 'Tax registration label override', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_tax_registration_label_override' ],
            'kitgenix_pdf_invoicing_localization'
        );

        $this->add_field(
            'show_item_sku',
            __( 'Show SKU', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_item_sku' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_item_meta',
            __( 'Show item meta', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_item_meta' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_item_tax',
            __( 'Show line-item tax', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_item_tax' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_payment_method',
            __( 'Show payment method', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_payment_method' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_transaction_id',
            __( 'Show transaction ID', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_transaction_id' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_shipping_method',
            __( 'Show shipping method', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_shipping_method' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_tax_totals',
            __( 'Show tax totals', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_tax_totals' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_customer_note',
            __( 'Show customer note', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_customer_note' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'show_internal_note',
            __( 'Show latest internal note', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_show_internal_note' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'custom_order_fields',
            __( 'Custom order fields', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_custom_order_fields' ],
            'kitgenix_pdf_invoicing_fields'
        );

        $this->add_field(
            'document_generation_rules',
            __( 'Availability rules', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_document_generation_rules' ],
            'kitgenix_pdf_invoicing_document_rules'
        );

        $this->add_field(
            'logo_id',
            __( 'Logo', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_logo_id' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'footer_text',
            __( 'Footer text', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_footer_text' ],
            'kitgenix_pdf_invoicing_main'
        );

        $this->add_field(
            'document_notes',
            __( 'Document notes', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_document_notes' ],
            'kitgenix_pdf_invoicing_main'
        );

        // Fields for brand & styling.
        $this->add_field(
            'template_style',
            __( 'Template style', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_template_style' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'primary_color',
            __( 'Primary color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_primary_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'accent_color',
            __( 'Accent color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_accent_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'text_color',
            __( 'Text color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_text_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'muted_text_color',
            __( 'Muted text color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_muted_text_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'border_color',
            __( 'Border color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_border_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'table_header_bg',
            __( 'Table header background', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_table_header_bg' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'background_color',
            __( 'Document background', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_background_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'footer_bg_color',
            __( 'Footer background', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_footer_bg_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'footer_text_color',
            __( 'Footer text color', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_footer_text_color' ],
            'kitgenix_pdf_invoicing_brand'
        );

        $this->add_field(
            'designer_header_alignment',
            __( 'Header alignment', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_header_alignment' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_logo_scale',
            __( 'Logo scale', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_logo_scale' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_density',
            __( 'Content density', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_density' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_panel_style',
            __( 'Panel style', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_panel_style' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_table_style',
            __( 'Order table style', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_table_style' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_totals_emphasis',
            __( 'Totals emphasis', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_totals_emphasis' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'designer_footer_alignment',
            __( 'Footer alignment', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_designer_footer_alignment' ],
            'kitgenix_pdf_invoicing_designer'
        );

        $this->add_field(
            'custom_font_family',
            __( 'Document font', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_custom_font_family' ],
            'kitgenix_pdf_invoicing_designer'
        );

        // Field for section 2: email attachments grid.
        $this->add_field(
            'email_attachments',
            __( 'Attach documents to emails', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            [ $this, 'field_email_attachments' ],
            'kitgenix_pdf_invoicing_email'
        );
    }

    protected function add_field( string $id, string $label, callable $callback, string $section_id ): void {
        add_settings_field(
            $id,
            $label,
            $callback,
            'kitgenix-pdf-invoicing-settings',
            $section_id,
            [
                'label_for' => $id,
            ]
        );
    }

    /**
     * Small, trusted, hardcoded inline SVG icons used in card headers.
     * Not user input – safe to echo unescaped.
     */
    private function icon( string $name ): string {
        $icons = [
            'building' => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M4 17.5V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v13.5M4 17.5h8M4 17.5H2.5M12 17.5h3.5M12 17.5V9a1 1 0 0 1 1-1h2.5a1 1 0 0 1 1 1v8.5M17.5 17.5H16M7 6h1M7 9h1M7 12h1" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'hash'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M8 3 6 17M14 3l-2 14M3.5 7.5h13M2.5 12.5h13" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'globe'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="10" cy="10" r="7" stroke="currentColor" stroke-width="1.4"/><path d="M3 10h14M10 3c2.2 2 3.2 4.4 3.2 7s-1 5-3.2 7c-2.2-2-3.2-4.4-3.2-7S7.8 5 10 3Z" stroke="currentColor" stroke-width="1.4"/></svg>',
            'list'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M7.5 5h9M7.5 10h9M7.5 15h9" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="3.5" cy="5" r="1" fill="currentColor"/><circle cx="3.5" cy="10" r="1" fill="currentColor"/><circle cx="3.5" cy="15" r="1" fill="currentColor"/></svg>',
            'palette'  => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10 17a7 7 0 1 1 0-14c3.9 0 7 2.7 7 6 0 1.7-1.1 2.5-2.5 2.5h-1.7c-.9 0-1.4.9-.9 1.6.6.9-.1 1.9-1.2 1.9H10Z" stroke="currentColor" stroke-width="1.4"/><circle cx="6.7" cy="9.5" r=".9" fill="currentColor"/><circle cx="9" cy="6.3" r=".9" fill="currentColor"/><circle cx="12.6" cy="6.8" r=".9" fill="currentColor"/></svg>',
            'brush'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 2.5c1 0 3 1 3 3 0 1.5-1.2 2.4-2.4 3.5L10 14.1a2 2 0 0 1-1.3.6l-3.4.3.3-3.4c0-.5.3-1 .6-1.3l5.1-5.1c1-1 2-2.7 3.2-2.7Z" stroke="currentColor" stroke-width="1.3" stroke-linejoin="round"/><path d="M4 17.5s.3-2 1.5-2.5c1-.4 1.8.3 1.8 1.2 0 1.3-1.6 1.3-3.3 1.3Z" stroke="currentColor" stroke-width="1.3" stroke-linejoin="round"/></svg>',
            'mail'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="2.5" y="4.5" width="15" height="11" rx="1.5" stroke="currentColor" stroke-width="1.4"/><path d="m3.5 6 6.5 5 6.5-5" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'activity' => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M2.5 10.5h3.2l1.8-5.5 3 10 1.8-4.5h5.2" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'heart'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10 17S3 12.6 3 7.8C3 5.4 4.9 3.5 7.2 3.5c1.2 0 2.3.6 2.8 1.5.5-.9 1.6-1.5 2.8-1.5 2.3 0 4.2 1.9 4.2 4.3 0 4.8-7 9.2-7 9.2Z" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/></svg>',
            'sync'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M16 10a6 6 0 0 1-10.6 3.8M4 10a6 6 0 0 1 10.6-3.8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><path d="M4 13.8V17h3.2M16 6.2V3h-3.2" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>',
            'tools'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12.5 4.5a3 3 0 0 0-3.9 3.9l-6.1 6.1 2 2 6.1-6.1a3 3 0 0 0 3.9-3.9l-2.1 2.1-2-2 2.1-2.1Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>',
            'check'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M4 10.5 8 14.5 16 6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'logs'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="3.5" y="3" width="13" height="14" rx="1.5" stroke="currentColor" stroke-width="1.5"/><path d="M6.5 7h7M6.5 10h7M6.5 13h4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>',
            'audit'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M5 3.5h7l3 3V16a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V4.5a1 1 0 0 1 1-1Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/><path d="M7 9h6M7 12h6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>',
            'chat'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M3.5 5.5a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v6a2 2 0 0 1-2 2H9l-3.5 3v-3a2 2 0 0 1-2-2v-6Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>',
            'star'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10 3.2l2.02 4.1 4.53.66-3.28 3.2.78 4.52L10 13.5l-4.05 2.13.78-4.52-3.28-3.2 4.53-.66L10 3.2Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>',
            'copy'     => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="7" y="7" width="9.5" height="9.5" rx="1.5" stroke="currentColor" stroke-width="1.5"/><path d="M13 7V4.5A1.5 1.5 0 0 0 11.5 3h-7A1.5 1.5 0 0 0 3 4.5v7A1.5 1.5 0 0 0 4.5 13H7" stroke="currentColor" stroke-width="1.5"/></svg>',
            'users'    => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="7" cy="7" r="2.5" stroke="currentColor" stroke-width="1.5"/><path d="M2.5 16c.5-3 2.2-4.5 4.5-4.5s4 1.5 4.5 4.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="14" cy="7.5" r="2" stroke="currentColor" stroke-width="1.5"/><path d="M12.5 11.3c1.8.2 3 1.5 3.5 4.2" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>',
            'search'   => '<svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="9" cy="9" r="6" stroke="currentColor" stroke-width="1.4"/><path d="m17 17-3.7-3.7" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/></svg>',
            'shield'   => '<svg width="14" height="14" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10 2.5l6 2.2v4.4c0 4.2-2.6 7.4-6 8.4-3.4-1-6-4.2-6-8.4V4.7l6-2.2Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/><path d="M7.3 10.2l1.9 1.9 3.5-3.9" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>',
            'paypal'   => '<svg width="18" height="18" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M6.7 15.5H4.9a.3.3 0 0 1-.3-.35L6.5 3.8a.5.5 0 0 1 .5-.4h4.4c2 0 3.4 1.2 3.1 3.2-.3 2.4-2.1 3.7-4.3 3.7H8.6a.5.5 0 0 0-.5.4l-.7 3.9a.5.5 0 0 1-.5.4Z" fill="currentColor" opacity=".55"/><path d="M9.2 15.5H7.4a.3.3 0 0 1-.3-.35L9 3.8a.5.5 0 0 1 .5-.4h4.4c2 0 3.4 1.2 3.1 3.2-.3 2.4-2.1 3.7-4.3 3.7h-1.6a.5.5 0 0 0-.5.4l-.7 3.9a.5.5 0 0 1-.5.4Z" fill="currentColor"/></svg>',
        ];

        return $icons[ $name ] ?? '';
    }

    /**
     * Field IDs whose control is wide (textarea/table/multi-part) and should
     * render with the label stacked above the control instead of beside it.
     *
     * @return string[]
     */
    private function stacked_field_ids(): array {
        return [
            'company_address',
            'footer_text',
            'document_notes',
            'custom_order_fields',
            'invoice_number_format',
            'receipt_number_format',
            'packing_slip_number_format',
            'credit_note_number_format',
            'logo_id',
            'email_attachments',
            'document_generation_rules',
        ];
    }

    /**
     * Render a registered settings section (title, description callback, and
     * its fields) as a Kitgenix card using the shared settings-row layout,
     * instead of WordPress's default form-table markup.
     */
    private function render_section_card( string $page_slug, string $section_id, string $icon_name = '' ): void {
        global $wp_settings_sections, $wp_settings_fields;

        if ( empty( $wp_settings_sections[ $page_slug ][ $section_id ] ) ) {
            return;
        }

        $section = $wp_settings_sections[ $page_slug ][ $section_id ];
        $icon_markup = $icon_name ? $this->icon( $icon_name ) : '';
        $stacked_ids = $this->stacked_field_ids();
        ?>
        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div class="kitgenix-card-head-main">
                    <?php if ( '' !== $icon_markup ) : ?>
                        <span class="kitgenix-card-icon" aria-hidden="true"><?php echo $icon_markup; /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?></span>
                    <?php endif; ?>
                    <div class="kitgenix-card-head-text">
                        <h2><?php echo esc_html( (string) ( $section['title'] ?? '' ) ); ?></h2>
                        <?php
                        if ( ! empty( $section['callback'] ) && is_callable( $section['callback'] ) ) {
                            call_user_func( $section['callback'], $section );
                        }
                        ?>
                    </div>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <div class="kitgenix-settings-group">
                    <?php
                    if ( ! empty( $wp_settings_fields[ $page_slug ][ $section_id ] ) ) {
                        foreach ( $wp_settings_fields[ $page_slug ][ $section_id ] as $field ) {
                            $field_id  = (string) $field['id'];
                            $label_for = (string) ( $field['args']['label_for'] ?? '' );
                            $stacked   = in_array( $field_id, $stacked_ids, true );
                            ?>
                            <div class="kitgenix-setting-row<?php echo $stacked ? ' kitgenix-setting-row-stacked' : ''; ?>">
                                <div class="kitgenix-setting-row-label">
                                    <?php if ( '' !== $label_for ) : ?>
                                        <label for="<?php echo esc_attr( $label_for ); ?>"><?php echo esc_html( (string) $field['title'] ); ?></label>
                                    <?php else : ?>
                                        <span><?php echo esc_html( (string) $field['title'] ); ?></span>
                                    <?php endif; ?>
                                </div>
                                <div class="kitgenix-setting-row-control">
                                    <?php call_user_func( $field['callback'], $field['args'] ); ?>
                                </div>
                            </div>
                            <?php
                        }
                    }
                    ?>
                </div>
            </div>
        </div>
        <?php
    }

    /**
     * Sanitize entire settings array.
     */
    public function sanitize_settings( $input ): array {
        $output   = [];
        $input    = is_array( $input ) ? $input : [];
        $defaults = Settings::get_all();

        // When processing settings via the WP Settings API ensure the request
        // originates from a privileged admin and carries a valid nonce.
        // Important: the Settings API nonce action is "{$option_group}-options"
        // and should only be required when this sanitize callback is invoked
        // as part of the options.php form submission (programmatic updates to
        // the option should not be blocked by missing POST data).
        $option_group = 'kitgenix_pdf_invoicing_for_woocommerce_';
        $posted_group = isset( $_POST['option_page'] ) ? sanitize_key( wp_unslash( $_POST['option_page'] ) ) : '';

        if ( is_admin() && $posted_group === $option_group ) {
            if ( ! current_user_can( 'manage_woocommerce' ) ) {
                return $defaults;
            }

            if ( ! isset( $_POST['_wpnonce'] ) ) {
                return $defaults;
            }

            $nonce = sanitize_text_field( wp_unslash( $_POST['_wpnonce'] ) );
            if ( ! wp_verify_nonce( $nonce, $option_group . '-options' ) ) {
                return $defaults;
            }
        }

        $output['company_name']    = sanitize_text_field( $input['company_name'] ?? $defaults['company_name'] );
        $output['company_address'] = wp_kses_post( $input['company_address'] ?? $defaults['company_address'] );
        $output['company_email']   = sanitize_email( $input['company_email'] ?? $defaults['company_email'] );
        $output['company_phone']   = sanitize_text_field( $input['company_phone'] ?? $defaults['company_phone'] );
        $output['tax_id']          = sanitize_text_field( $input['tax_id'] ?? $defaults['tax_id'] );
        $style = isset( $input['template_style'] ) ? sanitize_key( (string) $input['template_style'] ) : (string) ( $defaults['template_style'] ?? 'standard' );
        $allowed_styles = [ 'standard', 'simple', 'modern', 'business' ];
        $output['template_style'] = in_array( $style, $allowed_styles, true ) ? $style : 'standard';
        $designer_header_alignment = isset( $input['designer_header_alignment'] ) ? sanitize_key( (string) $input['designer_header_alignment'] ) : (string) $defaults['designer_header_alignment'];
        $designer_logo_scale       = isset( $input['designer_logo_scale'] ) ? sanitize_key( (string) $input['designer_logo_scale'] ) : (string) $defaults['designer_logo_scale'];
        $designer_density          = isset( $input['designer_density'] ) ? sanitize_key( (string) $input['designer_density'] ) : (string) $defaults['designer_density'];
        $designer_panel_style      = isset( $input['designer_panel_style'] ) ? sanitize_key( (string) $input['designer_panel_style'] ) : (string) $defaults['designer_panel_style'];
        $designer_table_style      = isset( $input['designer_table_style'] ) ? sanitize_key( (string) $input['designer_table_style'] ) : (string) $defaults['designer_table_style'];
        $designer_totals_emphasis  = isset( $input['designer_totals_emphasis'] ) ? sanitize_key( (string) $input['designer_totals_emphasis'] ) : (string) $defaults['designer_totals_emphasis'];
        $designer_footer_alignment = isset( $input['designer_footer_alignment'] ) ? sanitize_key( (string) $input['designer_footer_alignment'] ) : (string) $defaults['designer_footer_alignment'];

        $output['designer_header_alignment'] = in_array( $designer_header_alignment, [ 'left', 'center', 'right' ], true ) ? $designer_header_alignment : 'left';
        $output['designer_logo_scale']       = in_array( $designer_logo_scale, [ 'small', 'medium', 'large' ], true ) ? $designer_logo_scale : 'medium';
        $output['designer_density']          = in_array( $designer_density, [ 'compact', 'comfortable', 'spacious' ], true ) ? $designer_density : 'comfortable';
        $output['designer_panel_style']      = in_array( $designer_panel_style, [ 'minimal', 'boxed', 'tinted' ], true ) ? $designer_panel_style : 'minimal';
        $output['designer_table_style']      = in_array( $designer_table_style, [ 'clean', 'striped', 'grid' ], true ) ? $designer_table_style : 'clean';
        $output['designer_totals_emphasis']  = in_array( $designer_totals_emphasis, [ 'standard', 'boxed', 'highlight' ], true ) ? $designer_totals_emphasis : 'standard';
        $output['designer_footer_alignment'] = in_array( $designer_footer_alignment, [ 'left', 'center', 'right' ], true ) ? $designer_footer_alignment : 'left';

        // Only accept a font family that is actually a currently-uploaded
        // custom font – never an arbitrary string, since this value is
        // later interpolated into CSS output.
        $custom_font_family = isset( $input['custom_font_family'] ) ? sanitize_text_field( (string) $input['custom_font_family'] ) : '';
        $known_font_families = array_column( \Kitgenix\PDF_Invoicing\Modules\Invoicing\FontManager::get_fonts(), 'family' );
        $output['custom_font_family'] = in_array( $custom_font_family, $known_font_families, true ) ? $custom_font_family : '';

        $output['invoice_prefix']  = sanitize_text_field( $input['invoice_prefix'] ?? $defaults['invoice_prefix'] );
        $output['receipt_prefix']  = sanitize_text_field( $input['receipt_prefix'] ?? $defaults['receipt_prefix'] );
        $output['packing_slip_prefix'] = sanitize_text_field( $input['packing_slip_prefix'] ?? $defaults['packing_slip_prefix'] );
        $output['credit_note_prefix'] = sanitize_text_field( $input['credit_note_prefix'] ?? $defaults['credit_note_prefix'] );
        $output['invoice_number_format'] = sanitize_text_field( $input['invoice_number_format'] ?? $defaults['invoice_number_format'] );
        $output['receipt_number_format'] = sanitize_text_field( $input['receipt_number_format'] ?? $defaults['receipt_number_format'] );
        $output['packing_slip_number_format'] = sanitize_text_field( $input['packing_slip_number_format'] ?? $defaults['packing_slip_number_format'] );
        $output['credit_note_number_format'] = sanitize_text_field( $input['credit_note_number_format'] ?? $defaults['credit_note_number_format'] );

        $sequence_reset = isset( $input['number_sequence_reset'] ) ? sanitize_key( (string) $input['number_sequence_reset'] ) : (string) $defaults['number_sequence_reset'];
        $allowed_sequence_reset = [ 'none', 'calendar_year', 'fiscal_year' ];
        $output['number_sequence_reset'] = in_array( $sequence_reset, $allowed_sequence_reset, true ) ? $sequence_reset : 'none';

        $sequence_padding = isset( $input['number_sequence_padding'] ) ? absint( $input['number_sequence_padding'] ) : (int) $defaults['number_sequence_padding'];
        if ( $sequence_padding < 1 ) {
            $sequence_padding = 1;
        }
        if ( $sequence_padding > 12 ) {
            $sequence_padding = 12;
        }
        $output['number_sequence_padding'] = $sequence_padding;

        $fiscal_year_start_month = isset( $input['fiscal_year_start_month'] ) ? absint( $input['fiscal_year_start_month'] ) : (int) $defaults['fiscal_year_start_month'];
        if ( $fiscal_year_start_month < 1 || $fiscal_year_start_month > 12 ) {
            $fiscal_year_start_month = 1;
        }
        $output['fiscal_year_start_month'] = $fiscal_year_start_month;

        $allowed_localization_packs = array_keys( DocumentDisplay::get_localization_pack_options() );
        $localization_pack = isset( $input['localization_pack'] ) ? sanitize_key( (string) $input['localization_pack'] ) : (string) $defaults['localization_pack'];
        $output['localization_pack'] = in_array( $localization_pack, $allowed_localization_packs, true ) ? $localization_pack : 'standard';

        $tax_display_mode = isset( $input['tax_display_mode'] ) ? sanitize_key( (string) $input['tax_display_mode'] ) : (string) $defaults['tax_display_mode'];
        $output['tax_display_mode'] = in_array( $tax_display_mode, [ 'exclusive', 'inclusive' ], true ) ? $tax_display_mode : 'exclusive';

        $output['document_date_format'] = sanitize_text_field( $input['document_date_format'] ?? $defaults['document_date_format'] );
        $output['tax_label_override'] = sanitize_text_field( $input['tax_label_override'] ?? $defaults['tax_label_override'] );
        $output['tax_registration_label_override'] = sanitize_text_field( $input['tax_registration_label_override'] ?? $defaults['tax_registration_label_override'] );

        foreach ( [
            'show_currency_code',
            'show_item_sku',
            'show_item_meta',
            'show_item_tax',
            'show_payment_method',
            'show_transaction_id',
            'show_shipping_method',
            'show_tax_totals',
            'show_customer_note',
            'show_internal_note',
        ] as $boolean_setting ) {
            $output[ $boolean_setting ] = ! empty( $input[ $boolean_setting ] );
        }

        $custom_order_fields = isset( $input['custom_order_fields'] ) ? (string) $input['custom_order_fields'] : (string) $defaults['custom_order_fields'];
        $custom_order_lines  = preg_split( '/\r\n|\r|\n/', $custom_order_fields );
        $sanitized_custom_order_lines = [];
        if ( is_array( $custom_order_lines ) ) {
            foreach ( $custom_order_lines as $custom_order_line ) {
                $custom_order_line = sanitize_text_field( (string) $custom_order_line );
                if ( '' !== trim( $custom_order_line ) ) {
                    $sanitized_custom_order_lines[] = $custom_order_line;
                }
            }
        }
        $output['custom_order_fields'] = implode( "\n", $sanitized_custom_order_lines );

        $output['logo_id']         = isset( $input['logo_id'] ) ? absint( $input['logo_id'] ) : (int) $defaults['logo_id'];
        $output['footer_text']     = wp_kses_post( $input['footer_text'] ?? $defaults['footer_text'] );

        $output['document_notes'] = wp_kses_post( $input['document_notes'] ?? $defaults['document_notes'] );

        // Brand / styling colors.
        $output['primary_color']    = sanitize_hex_color( $input['primary_color'] ?? $defaults['primary_color'] );
        $output['accent_color']     = sanitize_hex_color( $input['accent_color'] ?? $defaults['accent_color'] );
        $output['text_color']       = sanitize_hex_color( $input['text_color'] ?? $defaults['text_color'] );
        $output['muted_text_color'] = sanitize_hex_color( $input['muted_text_color'] ?? $defaults['muted_text_color'] );
        $output['border_color']     = sanitize_hex_color( $input['border_color'] ?? $defaults['border_color'] );
        $output['table_header_bg']  = sanitize_hex_color( $input['table_header_bg'] ?? $defaults['table_header_bg'] );
        $output['background_color'] = sanitize_hex_color( $input['background_color'] ?? $defaults['background_color'] );
        $output['footer_bg_color']   = sanitize_hex_color( $input['footer_bg_color'] ?? $defaults['footer_bg_color'] );
        $output['footer_text_color'] = sanitize_hex_color( $input['footer_text_color'] ?? $defaults['footer_text_color'] );

        if ( ! array_key_exists( 'document_generation_rules', $input ) ) {
            $output['document_generation_rules'] = ( isset( $defaults['document_generation_rules'] ) && is_array( $defaults['document_generation_rules'] ) )
                ? $defaults['document_generation_rules']
                : Settings::get_default_document_generation_rules();
        } else {
            $default_document_rules = Settings::get_default_document_generation_rules();
            $input_document_rules   = is_array( $input['document_generation_rules'] ?? null ) ? (array) $input['document_generation_rules'] : [];
            $document_rule_output   = [];

            foreach ( $default_document_rules as $document_type => $rule_defaults ) {
                $rule_input = isset( $input_document_rules[ $document_type ] ) && is_array( $input_document_rules[ $document_type ] )
                    ? (array) $input_document_rules[ $document_type ]
                    : [];

                $status_parts = preg_split( '/[\s,]+/', (string) ( $rule_input['allowed_statuses'] ?? $rule_defaults['allowed_statuses'] ) );
                $allowed_statuses = [];
                if ( is_array( $status_parts ) ) {
                    foreach ( $status_parts as $status_part ) {
                        $status_part = sanitize_key( str_replace( 'wc-', '', (string) $status_part ) );
                        if ( '' !== $status_part ) {
                            $allowed_statuses[] = $status_part;
                        }
                    }
                }

                $payment_requirement = isset( $rule_input['payment_requirement'] ) ? sanitize_key( (string) $rule_input['payment_requirement'] ) : (string) $rule_defaults['payment_requirement'];
                if ( ! in_array( $payment_requirement, [ 'any', 'paid', 'unpaid' ], true ) ) {
                    $payment_requirement = 'any';
                }

                $document_rule_output[ $document_type ] = [
                    'enabled'             => ! empty( $rule_input['enabled'] ),
                    'allowed_statuses'    => implode( ',', array_values( array_unique( $allowed_statuses ) ) ),
                    'payment_requirement' => $payment_requirement,
                ];
            }

            $output['document_generation_rules'] = $document_rule_output;
        }

        // Email attachments: sanitize checkboxes.
        // IMPORTANT: this settings page is split into multiple <form> elements
        // (tabs). When saving a tab that does NOT contain the email attachments
        // matrix, `email_attachments` will not be posted at all.
        //
        // In that case, preserve the currently stored mapping instead of
        // resetting everything to false.
        if ( ! array_key_exists( 'email_attachments', $input ) ) {
            $output['email_attachments'] = ( isset( $defaults['email_attachments'] ) && is_array( $defaults['email_attachments'] ) )
                ? $defaults['email_attachments']
                : Settings::get_default_email_attachments();

            return $output;
        }

        $default_email_map = Settings::get_default_email_attachments();
        $document_types    = DocumentTypes::all();
        $input_map         = is_array( $input['email_attachments'] ?? null ) ? (array) $input['email_attachments'] : [];

        $email_output = [];

        foreach ( $default_email_map as $email_id => $doc_defaults ) {
            $email_output[ $email_id ] = [];

            $doc_input = isset( $input_map[ $email_id ] ) && is_array( $input_map[ $email_id ] )
                ? $input_map[ $email_id ]
                : [];

            foreach ( $document_types as $doc_type ) {
                $raw = $doc_input[ $doc_type ] ?? '';
                // Checkbox style – presence means "on".
                $email_output[ $email_id ][ $doc_type ] = ! empty( $raw );
            }
        }

        $output['email_attachments'] = $email_output;

        return $output;
    }

    /**
     * Individual field renderers.
     */

    public function field_company_name(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="company_name"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[company_name]"
               value="<?php echo esc_attr( $settings['company_name'] ); ?>"
               class="regular-text" />
        <?php
    }

    public function field_company_address(): void {
        $settings = Settings::get_all();
        ?>
        <textarea id="company_address"
                  name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[company_address]"
                  rows="3"
                  class="large-text"><?php echo esc_textarea( $settings['company_address'] ); ?></textarea>
        <p class="description">
            <?php esc_html_e( 'Shown as the “From” address on documents. Line breaks are preserved.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_company_email(): void {
        $settings = Settings::get_all();
        ?>
        <input type="email"
               id="company_email"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[company_email]"
               value="<?php echo esc_attr( $settings['company_email'] ); ?>"
               class="regular-text" />
        <?php
    }

    public function field_company_phone(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="company_phone"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[company_phone]"
               value="<?php echo esc_attr( $settings['company_phone'] ); ?>"
               class="regular-text" />
        <?php
    }

    public function field_tax_id(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="tax_id"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[tax_id]"
               value="<?php echo esc_attr( $settings['tax_id'] ); ?>"
               class="regular-text" />
        <p class="description">
            <?php esc_html_e( 'Tax/VAT registration number shown on invoices and credit notes.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_template_style(): void {
        $settings = Settings::get_all();

        $current = isset( $settings['template_style'] ) ? sanitize_key( (string) $settings['template_style'] ) : 'standard';
        $styles  = [
            'standard'  => __( 'Standard', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'simple'    => __( 'Simple', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'modern'    => __( 'Modern', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'business'  => __( 'Business', 'kitgenix-pdf-invoicing-for-woocommerce' ),
        ];
        ?>
        <select id="template_style" name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[template_style]">
            <?php foreach ( $styles as $key => $label ) : ?>
                <option value="<?php echo esc_attr( $key ); ?>" <?php selected( $current, $key ); ?>>
                    <?php echo esc_html( $label ); ?>
                </option>
            <?php endforeach; ?>
        </select>
        <p class="description">
            <?php esc_html_e( 'Choose the base PDF template pack to use for invoices, receipts, packing slips and credit notes.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_invoice_prefix(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="invoice_prefix"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[invoice_prefix]"
               value="<?php echo esc_attr( $settings['invoice_prefix'] ); ?>"
               class="regular-text" />
        <p class="description">
            <?php esc_html_e( 'Optional prefix added before the invoice number (e.g. KG-, INV-2025-).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_receipt_prefix(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="receipt_prefix"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[receipt_prefix]"
               value="<?php echo esc_attr( $settings['receipt_prefix'] ); ?>"
               class="regular-text" />
        <p class="description">
            <?php esc_html_e( 'Optional prefix added before the receipt number (falls back to invoice prefix if empty).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_credit_note_prefix(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="credit_note_prefix"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[credit_note_prefix]"
               value="<?php echo esc_attr( $settings['credit_note_prefix'] ); ?>"
               class="regular-text" />
        <p class="description">
            <?php esc_html_e( 'Prefix used for credit notes (default: CN-).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    protected function render_number_format_field( string $id, string $description ): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="<?php echo esc_attr( $id ); ?>"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[<?php echo esc_attr( $id ); ?>]"
               value="<?php echo esc_attr( $settings[ $id ] ?? '' ); ?>"
               class="large-text code" />
        <p class="description"><?php echo esc_html( $description ); ?></p>
        <p class="description"><?php esc_html_e( 'Supported tokens: {prefix}, {order_number}, {order_id}, {sequence}, {refund_sequence}, {year}, {yy}, {month}, {day}, {country}, {billing_country}, {shipping_country}, {fiscal_year}, {fiscal_year_short}, {fiscal_year_start}, {fiscal_year_end}. Issued documents keep their stored number even if you change this later.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_packing_slip_prefix(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="packing_slip_prefix"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[packing_slip_prefix]"
               value="<?php echo esc_attr( $settings['packing_slip_prefix'] ); ?>"
               class="regular-text" />
        <p class="description">
            <?php esc_html_e( 'Prefix used when packing slip formats include {prefix}. Default: PS-.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_invoice_number_format(): void {
        $this->render_number_format_field(
            'invoice_number_format',
            __( 'Default: {prefix}{order_number}. Use {sequence} when you want a resettable compliance counter instead of the WooCommerce order number.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_receipt_number_format(): void {
        $this->render_number_format_field(
            'receipt_number_format',
            __( 'Default: {prefix}{order_number}. You can add country or fiscal-year tokens for region-specific receipt rules.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_packing_slip_number_format(): void {
        $this->render_number_format_field(
            'packing_slip_number_format',
            __( 'Default: {prefix}{order_number}. Useful when fulfilment teams need packing slips with their own numbering scheme.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_credit_note_number_format(): void {
        $this->render_number_format_field(
            'credit_note_number_format',
            __( 'Default: {prefix}{order_number}-{refund_sequence}. Switch to {sequence} if you need a dedicated compliance counter for credit notes.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_number_sequence_reset(): void {
        $settings = Settings::get_all();
        $current  = isset( $settings['number_sequence_reset'] ) ? sanitize_key( (string) $settings['number_sequence_reset'] ) : 'none';
        $options  = [
            'none'          => __( 'Never reset', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'calendar_year' => __( 'Reset each calendar year', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'fiscal_year'   => __( 'Reset each fiscal year', 'kitgenix-pdf-invoicing-for-woocommerce' ),
        ];
        ?>
        <select id="number_sequence_reset" name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[number_sequence_reset]">
            <?php foreach ( $options as $value => $label ) : ?>
                <option value="<?php echo esc_attr( $value ); ?>" <?php selected( $current, $value ); ?>><?php echo esc_html( $label ); ?></option>
            <?php endforeach; ?>
        </select>
        <p class="description"><?php esc_html_e( 'Only affects number formats that include the {sequence} token.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_number_sequence_padding(): void {
        $settings = Settings::get_all();
        $value    = isset( $settings['number_sequence_padding'] ) ? absint( $settings['number_sequence_padding'] ) : 4;
        ?>
        <input type="number"
               id="number_sequence_padding"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[number_sequence_padding]"
               min="1"
               max="12"
               value="<?php echo esc_attr( (string) $value ); ?>"
               class="small-text" />
        <p class="description"><?php esc_html_e( 'Pads the {sequence} token with leading zeros. Example: 0001.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_fiscal_year_start_month(): void {
        $settings = Settings::get_all();
        $current  = isset( $settings['fiscal_year_start_month'] ) ? absint( $settings['fiscal_year_start_month'] ) : 1;
        ?>
        <select id="fiscal_year_start_month" name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[fiscal_year_start_month]">
            <?php for ( $month = 1; $month <= 12; $month++ ) : ?>
                <option value="<?php echo esc_attr( (string) $month ); ?>" <?php selected( $current, $month ); ?>>
                    <?php echo esc_html( wp_date( 'F', mktime( 0, 0, 0, $month, 1, 2000 ) ) ); ?>
                </option>
            <?php endfor; ?>
        </select>
        <p class="description"><?php esc_html_e( 'Used for {fiscal_year} tokens and fiscal-year sequence resets.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    protected function render_checkbox_field( string $id, string $description ): void {
        $settings = Settings::get_all();
        $checked  = ! empty( $settings[ $id ] );
        ?>
        <label class="kitgenix-toggle">
            <input type="checkbox"
                   class="kitgenix-toggle-input"
                   id="<?php echo esc_attr( $id ); ?>"
                   name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[<?php echo esc_attr( $id ); ?>]"
                   value="1"
                   <?php checked( $checked ); ?> />
            <span class="kitgenix-toggle-track"><span class="kitgenix-toggle-thumb"></span></span>
            <span class="kitgenix-toggle-label"><?php echo esc_html__( 'Enabled', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></span>
        </label>
        <p class="description"><?php echo esc_html( $description ); ?></p>
        <?php
    }

    public function field_show_item_sku(): void {
        $this->render_checkbox_field(
            'show_item_sku',
            __( 'Display product SKUs beneath line items on invoices, receipts, and packing slips.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_item_meta(): void {
        $this->render_checkbox_field(
            'show_item_meta',
            __( 'Display WooCommerce item meta such as variations, add-ons, and product options under each line item.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_item_tax(): void {
        $this->render_checkbox_field(
            'show_item_tax',
            __( 'Add per-line tax amounts beneath item descriptions when you need more detailed tax visibility.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_payment_method(): void {
        $this->render_checkbox_field(
            'show_payment_method',
            __( 'Show the WooCommerce payment method in document order-data sections.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_transaction_id(): void {
        $this->render_checkbox_field(
            'show_transaction_id',
            __( 'Show the payment gateway transaction ID when one is available.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_shipping_method(): void {
        $this->render_checkbox_field(
            'show_shipping_method',
            __( 'Show the selected shipping method. Useful for packing slips and fulfilment paperwork.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_tax_totals(): void {
        $this->render_checkbox_field(
            'show_tax_totals',
            __( 'Keep tax/VAT rows visible in totals tables. Disable if you want cleaner consumer-style documents.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_localization_pack(): void {
        $this->render_select_field(
            'localization_pack',
            DocumentDisplay::get_localization_pack_options(),
            __( 'Choose a preset pack for legal document titles and tax terminology. For example, Australia GST switches invoices to “Tax Invoice” and credit notes to “Adjustment Note”.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_tax_display_mode(): void {
        $this->render_select_field(
            'tax_display_mode',
            [
                'exclusive' => __( 'Tax exclusive (B2B style)', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'inclusive' => __( 'Tax inclusive (consumer style)', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Controls whether invoices, receipts, and credit-note amounts use excluding-tax or including-tax values in line-item and totals tables.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_document_date_format(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="document_date_format"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[document_date_format]"
               value="<?php echo esc_attr( (string) ( $settings['document_date_format'] ?? '' ) ); ?>"
               class="regular-text code"
               placeholder="d/m/Y" />
        <p class="description"><?php esc_html_e( 'Optional PHP/WordPress date format for generated documents. Leave empty to use the WooCommerce date format. Examples: d/m/Y, m/d/Y, Y-m-d.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_show_currency_code(): void {
        $this->render_checkbox_field(
            'show_currency_code',
            __( 'Append the ISO currency code (for example EUR, USD, GBP, AUD) after formatted amounts for cross-border clarity.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_tax_label_override(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="tax_label_override"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[tax_label_override]"
               value="<?php echo esc_attr( (string) ( $settings['tax_label_override'] ?? '' ) ); ?>"
               class="regular-text"
               placeholder="VAT / GST / Sales Tax" />
        <p class="description"><?php esc_html_e( 'Optional. Override the pack tax term used in labels such as “Price (Excl. VAT)” or tax rows. Useful for translated labels like TVA, MwSt, IVA, or GST.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_tax_registration_label_override(): void {
        $settings = Settings::get_all();
        ?>
        <input type="text"
               id="tax_registration_label_override"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[tax_registration_label_override]"
               value="<?php echo esc_attr( (string) ( $settings['tax_registration_label_override'] ?? '' ) ); ?>"
               class="regular-text"
               placeholder="VAT Number / ABN / GST Number" />
        <p class="description"><?php esc_html_e( 'Optional. Override the company tax-registration label shown next to your stored tax/VAT ID.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_show_customer_note(): void {
        $this->render_checkbox_field(
            'show_customer_note',
            __( 'Show the order customer note on generated PDFs when one exists.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_show_internal_note(): void {
        $this->render_checkbox_field(
            'show_internal_note',
            __( 'Show the latest private WooCommerce order note. Enable only if you are comfortable exposing internal notes on generated PDFs.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_custom_order_fields(): void {
        $settings = Settings::get_all();
        ?>
        <textarea id="custom_order_fields"
                  name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[custom_order_fields]"
                  rows="5"
                  class="large-text code"><?php echo esc_textarea( $settings['custom_order_fields'] ?? '' ); ?></textarea>
        <p class="description"><?php esc_html_e( 'Add one WooCommerce order meta key per line using meta_key|Label. Example: _tracking_number|Tracking Number or _warehouse_pick_ref|Warehouse Pick Ref.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <p class="description"><?php esc_html_e( 'These rows are shown in the document order-data section when the chosen meta value exists on the order.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    public function field_document_generation_rules(): void {
        $settings       = Settings::get_all();
        $stored_rules   = isset( $settings['document_generation_rules'] ) && is_array( $settings['document_generation_rules'] )
            ? $settings['document_generation_rules']
            : [];
        $default_rules  = Settings::get_default_document_generation_rules();
        $document_types = array_keys( $default_rules );
        ?>
        <div class="kitgenix-table-wrap">
            <table class="kitgenix-table kitgenix-pdf-email-attachments-table">
                <thead>
                <tr>
                    <th><?php esc_html_e( 'Document', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                    <th class="kitgenix-align-center"><?php esc_html_e( 'Enabled', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                    <th><?php esc_html_e( 'Allowed order statuses', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                    <th><?php esc_html_e( 'Payment requirement', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                </tr>
                </thead>
                <tbody>
                <?php foreach ( $document_types as $document_type ) : ?>
                    <?php
                    $rule = isset( $stored_rules[ $document_type ] ) && is_array( $stored_rules[ $document_type ] )
                        ? wp_parse_args( $stored_rules[ $document_type ], $default_rules[ $document_type ] )
                        : $default_rules[ $document_type ];
                    $status_value = (string) ( $rule['allowed_statuses'] ?? '' );
                    $payment_rule = isset( $rule['payment_requirement'] ) ? sanitize_key( (string) $rule['payment_requirement'] ) : 'any';
                    ?>
                    <tr data-kitgenix-table-row>
                        <td>
                            <strong><?php echo esc_html( DocumentTypes::get_label( $document_type ) ); ?></strong>
                        </td>
                        <td class="kitgenix-align-center">
                            <label class="kitgenix-toggle">
                                <input type="checkbox"
                                       class="kitgenix-toggle-input"
                                       name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[document_generation_rules][<?php echo esc_attr( $document_type ); ?>][enabled]"
                                       value="1"
                                       <?php checked( ! empty( $rule['enabled'] ) ); ?> />
                                <span class="kitgenix-toggle-track"><span class="kitgenix-toggle-thumb"></span></span>
                            </label>
                        </td>
                        <td>
                            <input type="text"
                                   class="regular-text"
                                   name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[document_generation_rules][<?php echo esc_attr( $document_type ); ?>][allowed_statuses]"
                                   value="<?php echo esc_attr( $status_value ); ?>"
                                   placeholder="processing,completed" />
                            <p class="description"><?php esc_html_e( 'Optional comma-separated WooCommerce statuses without the wc- prefix. Leave empty to allow all statuses.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                        </td>
                        <td>
                            <select name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[document_generation_rules][<?php echo esc_attr( $document_type ); ?>][payment_requirement]">
                                <option value="any" <?php selected( $payment_rule, 'any' ); ?>><?php esc_html_e( 'Any payment state', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></option>
                                <option value="paid" <?php selected( $payment_rule, 'paid' ); ?>><?php esc_html_e( 'Paid orders only', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></option>
                                <option value="unpaid" <?php selected( $payment_rule, 'unpaid' ); ?>><?php esc_html_e( 'Unpaid orders only', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></option>
                            </select>
                        </td>
                    </tr>
                <?php endforeach; ?>
                </tbody>
            </table>
        </div>
        <p class="description">
            <?php esc_html_e( 'These rules are enforced for admin previews, batch exports, email attachments, and any document generated through the shared PDF pipeline.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_document_notes(): void {
        $settings = Settings::get_all();
        ?>
        <textarea id="document_notes"
                  name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[document_notes]"
                  rows="3"
                  class="large-text"><?php echo esc_textarea( $settings['document_notes'] ); ?></textarea>
        <p class="description">
            <?php esc_html_e( 'Optional notes shown on documents (invoices, receipts).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    public function field_logo_id(): void {
        $settings = Settings::get_all();
        $logo_id  = isset( $settings['logo_id'] ) ? (int) $settings['logo_id'] : 0;
        $logo_url = $logo_id ? wp_get_attachment_image_url( $logo_id, 'full' ) : '';
        $remove_class = 'button button-link-delete kitgenix-pdf-invoicing-for-woocommerce-logo-remove';
        if ( ! $logo_id ) {
            $remove_class .= ' kitgenix-is-hidden';
        }
        ?>
        <div class="kitgenix-pdf-invoicing-for-woocommerce-logo-field">
            <input
                type="hidden"
                id="logo_id"
                class="kitgenix-pdf-invoicing-for-woocommerce-logo-id-field"
                name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[logo_id]"
                value="<?php echo esc_attr( $logo_id ); ?>"
            />

            <div class="kitgenix-pdf-invoicing-for-woocommerce-logo-preview">
                <?php if ( $logo_url ) : ?>
                    <img src="<?php echo esc_url( $logo_url ); ?>" alt="">
                <?php endif; ?>
            </div>

            <div class="kitgenix-button-group">
                <button
                    type="button"
                    class="button kitgenix-pdf-invoicing-for-woocommerce-logo-select"
                    data-frame-title="<?php esc_attr_e( 'Select logo', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>"
                    data-frame-button="<?php esc_attr_e( 'Use this logo', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>"
                >
                    <?php esc_html_e( 'Select logo', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                </button>

                <button
                    type="button"
                    class="<?php echo esc_attr( $remove_class ); ?>"
                >
                    <?php esc_html_e( 'Remove logo', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                </button>
            </div>

            <p class="description">
                <?php esc_html_e( 'Choose a logo image from your media library. It will be shown on your documents.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
            </p>
        </div>
        <?php
    }

    public function field_footer_text(): void {
        $settings = Settings::get_all();
        ?>
        <textarea id="footer_text"
                  name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[footer_text]"
                  rows="3"
                  class="large-text"><?php echo esc_textarea( $settings['footer_text'] ); ?></textarea>
        <p class="description">
            <?php esc_html_e( 'Optional footer text, e.g. terms, thank you message, or bank details.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    /**
     * Color picker fields.
     */

    protected function render_color_field( string $id, string $description = '' ): void {
        $settings = Settings::get_all();
        $value    = $settings[ $id ] ?? '';
        ?>
        <input type="text"
               id="<?php echo esc_attr( $id ); ?>"
               name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[<?php echo esc_attr( $id ); ?>]"
               value="<?php echo esc_attr( $value ); ?>"
               class="kitgenix-pdf-invoicing-for-woocommerce-color-field"
               data-default-color="<?php echo esc_attr( $value ); ?>" />
        <?php if ( $description ) : ?>
            <p class="description"><?php echo esc_html( $description ); ?></p>
        <?php endif; ?>
        <?php
    }

    protected function render_select_field( string $id, array $options, string $description = '' ): void {
        $settings = Settings::get_all();
        $value    = isset( $settings[ $id ] ) ? sanitize_key( (string) $settings[ $id ] ) : '';
        ?>
        <select id="<?php echo esc_attr( $id ); ?>" name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[<?php echo esc_attr( $id ); ?>]">
            <?php foreach ( $options as $option_value => $option_label ) : ?>
                <option value="<?php echo esc_attr( $option_value ); ?>" <?php selected( $value, $option_value ); ?>>
                    <?php echo esc_html( $option_label ); ?>
                </option>
            <?php endforeach; ?>
        </select>
        <?php if ( $description ) : ?>
            <p class="description"><?php echo esc_html( $description ); ?></p>
        <?php endif; ?>
        <?php
    }

    public function field_primary_color(): void {
        $this->render_color_field(
            'primary_color',
            __( 'Used for main headings and key labels.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_accent_color(): void {
        $this->render_color_field(
            'accent_color',
            __( 'Used for accent lines and subtle highlights.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_text_color(): void {
        $this->render_color_field(
            'text_color',
            __( 'Main body text color.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_muted_text_color(): void {
        $this->render_color_field(
            'muted_text_color',
            __( 'Secondary labels and small text.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_border_color(): void {
        $this->render_color_field(
            'border_color',
            __( 'Borders around tables and sections.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_table_header_bg(): void {
        $this->render_color_field(
            'table_header_bg',
            __( 'Background for table headers.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_background_color(): void {
        $this->render_color_field(
            'background_color',
            __( 'Overall document background color.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_footer_bg_color(): void {
        $this->render_color_field(
            'footer_bg_color',
            __( 'Background colour used in the document footer.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_footer_text_color(): void {
        $this->render_color_field(
            'footer_text_color',
            __( 'Text colour used in the document footer.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_header_alignment(): void {
        $this->render_select_field(
            'designer_header_alignment',
            [
                'left'   => __( 'Left aligned', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'center' => __( 'Centered', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'right'  => __( 'Right aligned', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Align the logo block, company header, and document title without editing a template file.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_logo_scale(): void {
        $this->render_select_field(
            'designer_logo_scale',
            [
                'small'  => __( 'Small', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'medium' => __( 'Medium', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'large'  => __( 'Large', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Scale the document logo for compact invoices or more brand-led layouts.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_density(): void {
        $this->render_select_field(
            'designer_density',
            [
                'compact'     => __( 'Compact', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'comfortable' => __( 'Comfortable', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'spacious'    => __( 'Spacious', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Control table spacing, note padding, and overall document density for the bundled layouts.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_panel_style(): void {
        $this->render_select_field(
            'designer_panel_style',
            [
                'minimal' => __( 'Minimal', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'boxed'   => __( 'Boxed', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'tinted'  => __( 'Tinted', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Change the presentation of address, order-data, and notes panels without touching PHP templates.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_table_style(): void {
        $this->render_select_field(
            'designer_table_style',
            [
                'clean'   => __( 'Clean', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'striped' => __( 'Striped rows', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'grid'    => __( 'Grid borders', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Restyle the main order-items table for a cleaner invoice, zebra rows, or a full grid look.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_totals_emphasis(): void {
        $this->render_select_field(
            'designer_totals_emphasis',
            [
                'standard'  => __( 'Standard', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'boxed'     => __( 'Boxed totals panel', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'highlight' => __( 'Highlight final total', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Draw more or less attention to the totals area without creating a custom template override.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_designer_footer_alignment(): void {
        $this->render_select_field(
            'designer_footer_alignment',
            [
                'left'   => __( 'Left aligned', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'center' => __( 'Centered', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                'right'  => __( 'Right aligned', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            ],
            __( 'Align footer text for legal copy, payment details, or a cleaner branded finish.', 'kitgenix-pdf-invoicing-for-woocommerce' )
        );
    }

    public function field_custom_font_family(): void {
        $settings = Settings::get_all();
        $current  = isset( $settings['custom_font_family'] ) ? (string) $settings['custom_font_family'] : '';
        $choices  = \Kitgenix\PDF_Invoicing\Modules\Invoicing\FontManager::get_font_choices();
        ?>
        <select name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[custom_font_family]">
            <?php foreach ( $choices as $value => $label ) : ?>
                <option value="<?php echo esc_attr( $value ); ?>" <?php selected( $current, $value ); ?>><?php echo esc_html( $label ); ?></option>
            <?php endforeach; ?>
        </select>
        <p class="kitgenix-setting-row-desc"><?php esc_html_e( 'Applies to the whole document body. Manage uploaded fonts below the save button on this tab.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
        <?php
    }

    /**
     * Font upload/list/delete UI. Rendered as its own set of forms OUTSIDE
     * the main settings <form> (HTML forbids nested <form> elements, and
     * this needs its own multipart-encoded, non-Settings-API admin-post
     * handler for the file upload).
     */
    private function render_font_management_tools(): void {
        $fonts = \Kitgenix\PDF_Invoicing\Modules\Invoicing\FontManager::get_fonts();
        ?>
        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div class="kitgenix-card-head-text">
                    <h2><?php esc_html_e( 'Custom Fonts', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php esc_html_e( 'Only local .ttf/.otf/.woff uploads are accepted – never a remote URL. You are responsible for the licensing of any font you upload and embed in generated PDFs.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <div class="kitgenix-table-wrap">
                    <table class="kitgenix-table">
                        <thead>
                            <tr>
                                <th><?php esc_html_e( 'Family', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                <th><?php esc_html_e( 'Uploaded', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                <th></th>
                            </tr>
                        </thead>
                        <tbody>
                            <?php if ( empty( $fonts ) ) : ?>
                                <tr><td colspan="3"><?php esc_html_e( 'No custom fonts uploaded yet.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td></tr>
                            <?php endif; ?>
                            <?php foreach ( $fonts as $font_key => $font ) : ?>
                                <tr>
                                    <td><?php echo esc_html( (string) ( $font['family'] ?? '' ) ); ?></td>
                                    <td><?php echo esc_html( (string) ( $font['uploaded_at'] ?? '' ) ); ?></td>
                                    <td>
                                        <a class="kitgenix-link-danger" href="<?php echo esc_url( wp_nonce_url( admin_url( 'admin-post.php?action=kitgenix_pdf_invoicing_delete_font&font_key=' . rawurlencode( (string) $font_key ) ), 'kitgenix_pdf_invoicing_delete_font' ) ); ?>" onclick="return confirm('<?php echo esc_js( __( 'Delete this font? Documents already generated are unaffected; future documents will fall back to the template default.', 'kitgenix-pdf-invoicing-for-woocommerce' ) ); ?>');"><?php esc_html_e( 'Delete', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                                    </td>
                                </tr>
                            <?php endforeach; ?>
                        </tbody>
                    </table>
                </div>

                <form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" enctype="multipart/form-data" style="margin-top:10px;">
                    <input type="hidden" name="action" value="kitgenix_pdf_invoicing_upload_font" />
                    <?php wp_nonce_field( 'kitgenix_pdf_invoicing_upload_font' ); ?>
                    <input type="text" name="font_family" placeholder="<?php echo esc_attr__( 'Font family name, e.g. Acme Sans', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" required />
                    <input type="file" name="font_file" accept=".ttf,.otf,.woff" required />
                    <button type="submit" class="button"><?php esc_html_e( 'Upload font', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></button>
                </form>
            </div>
        </div>
        <?php
    }

    /**
     * Email attachments matrix: email ID × document type checkboxes.
     */
    public function field_email_attachments(): void {
        $settings      = Settings::get_all();
        $current_map   = isset( $settings['email_attachments'] ) && is_array( $settings['email_attachments'] )
            ? $settings['email_attachments']
            : [];
        $default_map   = Settings::get_default_email_attachments();
        $document_types = DocumentTypes::all();

        // Merge current with defaults so new doc types/emails appear automatically.
        foreach ( $default_map as $email_id => $doc_defaults ) {
            if ( ! isset( $current_map[ $email_id ] ) || ! is_array( $current_map[ $email_id ] ) ) {
                $current_map[ $email_id ] = $doc_defaults;
            } else {
                $current_map[ $email_id ] = wp_parse_args( $current_map[ $email_id ], $doc_defaults );
            }
        }

        $email_labels = EmailModule::get_supported_email_labels();
        ?>
        <div class="kitgenix-table-wrap">
            <table class="kitgenix-table kitgenix-pdf-email-attachments-table">
                <thead>
                <tr>
                    <th><?php esc_html_e( 'Email', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                    <?php foreach ( $document_types as $doc_type ) : ?>
                        <th class="kitgenix-align-center">
                            <?php echo esc_html( DocumentTypes::get_label( $doc_type ) ); ?>
                        </th>
                    <?php endforeach; ?>
                </tr>
                </thead>
                <tbody>
                <?php foreach ( $default_map as $email_id => $doc_defaults ) : ?>
                    <tr data-kitgenix-table-row>
                        <td>
                            <?php echo esc_html( $email_labels[ $email_id ] ?? $email_id ); ?>
                        </td>
                        <?php foreach ( $document_types as $doc_type ) : ?>
                            <?php
                            $checked = ! empty( $current_map[ $email_id ][ $doc_type ] );
                            ?>
                            <td class="kitgenix-align-center">
                                <label class="kitgenix-toggle">
                                    <input type="checkbox"
                                           class="kitgenix-toggle-input"
                                           name="<?php echo esc_attr( Settings::OPTION_KEY ); ?>[email_attachments][<?php echo esc_attr( $email_id ); ?>][<?php echo esc_attr( $doc_type ); ?>]"
                                           value="1"
                                           <?php checked( $checked ); ?>
                                    />
                                    <span class="kitgenix-toggle-track"><span class="kitgenix-toggle-thumb"></span></span>
                                </label>
                            </td>
                        <?php endforeach; ?>
                    </tr>
                <?php endforeach; ?>
                </tbody>
            </table>
        </div>
        <p class="description">
            <?php esc_html_e( 'Tick which documents should be attached to each email. You can still override this with filters if needed.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
        </p>
        <?php
    }

    /**
     * @return array{order_id:int,email_id:string,recipient_email:string}
     */
    protected function get_email_test_tools_state(): array {
        $email_labels     = EmailModule::get_supported_email_labels();
        $default_email_id = array_key_first( $email_labels );
        $recipient_email  = $this->get_default_test_email_recipient();
        $order_id         = 0;
        $email_id         = is_string( $default_email_id ) ? $default_email_id : 'customer_processing_order';

        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
        if ( isset( $_GET['email_preview_order_id'] ) ) {
            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
            $order_id = absint( wp_unslash( $_GET['email_preview_order_id'] ) );
        }

        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
        if ( isset( $_GET['email_preview_email_id'] ) ) {
            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
            $requested_email_id = sanitize_key( wp_unslash( $_GET['email_preview_email_id'] ) );
            if ( isset( $email_labels[ $requested_email_id ] ) ) {
                $email_id = $requested_email_id;
            }
        }

        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
        if ( isset( $_GET['email_test_recipient'] ) ) {
            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only state for preview UI. */
            $requested_recipient = sanitize_email( wp_unslash( $_GET['email_test_recipient'] ) );
            if ( '' !== $requested_recipient ) {
                $recipient_email = $requested_recipient;
            }
        }

        return [
            'order_id'        => $order_id,
            'email_id'        => $email_id,
            'recipient_email' => $recipient_email,
        ];
    }

    protected function get_default_test_email_recipient(): string {
        $current_user_email = '';
        if ( function_exists( 'wp_get_current_user' ) ) {
            $current_user = wp_get_current_user();
            if ( $current_user instanceof \WP_User ) {
                $current_user_email = (string) $current_user->user_email;
            }
        }

        if ( '' !== $current_user_email && is_email( $current_user_email ) ) {
            return $current_user_email;
        }

        return sanitize_email( (string) get_option( 'admin_email', '' ) );
    }

    protected function get_document_preview_action( string $document_type ): string {
        return in_array( $document_type, DocumentTypes::all(), true )
            ? DocumentTypes::get_admin_stream_action( $document_type )
            : '';
    }

    protected function get_document_preview_url( int $order_id, string $document_type ): string {
        $action = $this->get_document_preview_action( $document_type );
        if ( '' === $action ) {
            return '';
        }

        return add_query_arg(
            [
                'action'   => $action,
                'order_id' => $order_id,
                'nonce'    => wp_create_nonce( 'kitgenix_admin_pdf' ),
            ],
            admin_url( 'admin-post.php' )
        );
    }

    protected function render_email_test_tools(): void {
        if ( ! $this->email_module instanceof EmailModule ) {
            return;
        }

        $state        = $this->get_email_test_tools_state();
        $email_labels = EmailModule::get_supported_email_labels();
        $preview      = null;
        $preview_error = '';

        if ( $state['order_id'] > 0 ) {
            $order = wc_get_order( $state['order_id'] );

            if ( ! $order instanceof \WC_Order ) {
                $preview_error = __( 'The selected WooCommerce order could not be found.', 'kitgenix-pdf-invoicing-for-woocommerce' );
            } else {
                $preview = $this->email_module->get_email_preview_data( $state['email_id'], $order );
            }
        }
        ?>
        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div class="kitgenix-card-head-main">
                    <span class="kitgenix-card-icon" aria-hidden="true"><?php echo $this->icon( 'mail' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?></span>
                    <div class="kitgenix-card-head-text">
                        <h2><?php esc_html_e( 'Email Preview & Test Send', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                        <p><?php esc_html_e( 'Preview the PDF documents currently mapped to a WooCommerce email for a specific order, then send those same attachments to a safe inbox before rolling the workflow out live.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                    </div>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <form action="<?php echo esc_url( admin_url( 'admin.php' ) ); ?>" method="get">
                    <input type="hidden" name="page" value="kitgenix-pdf-invoicing-settings" />
                    <input type="hidden" name="tab" value="emails" />

                    <div class="kitgenix-settings-group">
                        <div class="kitgenix-setting-row">
                            <div class="kitgenix-setting-row-label">
                                <label for="kitgenix-email-preview-order-id"><?php esc_html_e( 'Order ID', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></label>
                                <p class="kitgenix-setting-row-desc"><?php esc_html_e( 'Enter the WooCommerce order you want to inspect.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                            </div>
                            <div class="kitgenix-setting-row-control">
                                <input type="number"
                                       min="1"
                                       step="1"
                                       id="kitgenix-email-preview-order-id"
                                       name="email_preview_order_id"
                                       value="<?php echo esc_attr( (string) $state['order_id'] ); ?>"
                                       class="small-text" />
                            </div>
                        </div>
                        <div class="kitgenix-setting-row">
                            <div class="kitgenix-setting-row-label">
                                <label for="kitgenix-email-preview-email-id"><?php esc_html_e( 'WooCommerce email', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></label>
                            </div>
                            <div class="kitgenix-setting-row-control">
                                <select id="kitgenix-email-preview-email-id" name="email_preview_email_id">
                                    <?php foreach ( $email_labels as $email_id => $label ) : ?>
                                        <option value="<?php echo esc_attr( $email_id ); ?>" <?php selected( $state['email_id'], $email_id ); ?>>
                                            <?php echo esc_html( $label ); ?>
                                        </option>
                                    <?php endforeach; ?>
                                </select>
                            </div>
                        </div>
                        <div class="kitgenix-setting-row">
                            <div class="kitgenix-setting-row-label">
                                <label for="kitgenix-email-preview-recipient"><?php esc_html_e( 'Test recipient', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></label>
                                <p class="kitgenix-setting-row-desc"><?php esc_html_e( 'This address is only used by the test-send action below.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                            </div>
                            <div class="kitgenix-setting-row-control">
                                <input type="email"
                                       id="kitgenix-email-preview-recipient"
                                       name="email_test_recipient"
                                       value="<?php echo esc_attr( $state['recipient_email'] ); ?>"
                                       class="regular-text" />
                            </div>
                        </div>
                    </div>

                    <div class="kitgenix-button-group">
                        <?php submit_button( __( 'Preview email attachments', 'kitgenix-pdf-invoicing-for-woocommerce' ), 'secondary', 'preview_email_attachments', false ); ?>
                    </div>
                </form>

                <p class="description">
                    <?php esc_html_e( 'Preview links open the live admin PDF stream and may generate or archive the selected document if it has not already been issued for that order.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                </p>

                <?php if ( '' !== $preview_error ) : ?>
                    <div class="kitgenix-notice kitgenix-notice-error" role="alert">
                        <div class="kitgenix-notice-body">
                            <p class="kitgenix-notice-text"><?php echo esc_html( $preview_error ); ?></p>
                        </div>
                    </div>
                <?php endif; ?>

                <?php if ( is_array( $preview ) ) : ?>
                    <p>
                        <?php
                        echo esc_html(
                            sprintf(
                                /* translators: 1: WooCommerce order number, 2: email workflow label. */
                                __( 'Previewing order #%1$s against %2$s.', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                                $state['order_id'],
                                (string) $preview['email_label']
                            )
                        );
                        ?>
                    </p>

                    <?php if ( empty( $preview['documents'] ) ) : ?>
                        <div class="kitgenix-notice kitgenix-notice-warning" role="status">
                            <div class="kitgenix-notice-body">
                                <p class="kitgenix-notice-text"><?php esc_html_e( 'No PDF documents are currently mapped to that WooCommerce email workflow. Update the attachment matrix above and save changes first.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                            </div>
                        </div>
                    <?php else : ?>
                        <div class="kitgenix-table-wrap">
                            <table class="kitgenix-table kitgenix-pdf-email-attachments-table">
                                <thead>
                                <tr>
                                    <th><?php esc_html_e( 'Document', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                    <th><?php esc_html_e( 'Status', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                    <th><?php esc_html_e( 'Preview', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                </tr>
                                </thead>
                                <tbody>
                                <?php foreach ( $preview['documents'] as $document ) : ?>
                                    <?php $preview_url = ! empty( $document['eligible'] ) ? $this->get_document_preview_url( $state['order_id'], (string) $document['type'] ) : ''; ?>
                                    <tr data-kitgenix-table-row>
                                        <td><?php echo esc_html( (string) $document['label'] ); ?></td>
                                        <td>
                                            <?php if ( ! empty( $document['eligible'] ) ) : ?>
                                                <span class="kitgenix-badge success kitgenix-badge-dot"><?php esc_html_e( 'Ready to preview and attach.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></span>
                                            <?php else : ?>
                                                <span class="kitgenix-badge neutral"><?php echo esc_html( (string) $document['reason'] ?: __( 'Unavailable for this order.', 'kitgenix-pdf-invoicing-for-woocommerce' ) ); ?></span>
                                            <?php endif; ?>
                                        </td>
                                        <td>
                                            <?php if ( '' !== $preview_url ) : ?>
                                                <a class="button button-secondary" href="<?php echo esc_url( $preview_url ); ?>" target="_blank" rel="noopener noreferrer"><?php esc_html_e( 'Open preview', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                                            <?php else : ?>
                                                <span class="description"><?php esc_html_e( 'No preview available', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></span>
                                            <?php endif; ?>
                                        </td>
                                    </tr>
                                <?php endforeach; ?>
                                </tbody>
                            </table>
                        </div>

                        <?php if ( ! empty( $preview['eligible_documents'] ) ) : ?>
                            <form action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" method="post" class="kitgenix-email-test-send-form">
                                <input type="hidden" name="action" value="<?php echo esc_attr( EmailModule::TEST_EMAIL_ACTION ); ?>" />
                                <input type="hidden" name="order_id" value="<?php echo esc_attr( (string) $state['order_id'] ); ?>" />
                                <input type="hidden" name="email_id" value="<?php echo esc_attr( $state['email_id'] ); ?>" />
                                <?php wp_nonce_field( 'kitgenix_pdf_test_email_send' ); ?>

                                <div class="kitgenix-settings-group">
                                    <div class="kitgenix-setting-row">
                                        <div class="kitgenix-setting-row-label">
                                            <label for="kitgenix-email-test-recipient-send"><?php esc_html_e( 'Send test email to', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></label>
                                            <p class="kitgenix-setting-row-desc"><?php esc_html_e( 'The test email sends the configured PDF attachments only, so you can validate the document set without triggering the live WooCommerce email template.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                                        </div>
                                        <div class="kitgenix-setting-row-control">
                                            <input type="email"
                                                   id="kitgenix-email-test-recipient-send"
                                                   name="recipient_email"
                                                   value="<?php echo esc_attr( $state['recipient_email'] ); ?>"
                                                   class="regular-text"
                                                   required />
                                        </div>
                                    </div>
                                </div>

                                <div class="kitgenix-button-group">
                                    <?php submit_button( __( 'Send test email with PDFs', 'kitgenix-pdf-invoicing-for-woocommerce' ), 'primary', 'send_test_email', false ); ?>
                                </div>
                            </form>
                        <?php else : ?>
                            <div class="kitgenix-notice kitgenix-notice-warning" role="status">
                                <div class="kitgenix-notice-body">
                                    <p class="kitgenix-notice-text"><?php esc_html_e( 'No mapped PDF documents are currently eligible for this order, so the test-send action is unavailable.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                                </div>
                            </div>
                        <?php endif; ?>
                    <?php endif; ?>
                <?php endif; ?>
            </div>
        </div>
        <?php
    }

    public function render_settings_page(): void {
        $ver = defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_VERSION' ) ? (string) KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_VERSION : '1.1.2';
        $social_base = ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL' ) ? (string) KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL : plugin_dir_url( __FILE__ ) ) . 'assets/images/social-media/';

        $default_tab = 'settings';
        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- non-actionable UI helper */
        if ( isset( $_GET['tab'] ) ) {
            /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- non-actionable UI helper */
            $maybe_tab = sanitize_key( wp_unslash( $_GET['tab'] ) );
            if ( in_array( $maybe_tab, [ 'settings', 'branding', 'emails', 'status', 'support', 'log' ], true ) ) {
                $default_tab = $maybe_tab;
            }
        }

        $base_tab_url = admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings' );
        ?>
        <div class="wrap kitgenix-admin-app kitgenix-pdf-invoicing-for-woocommerce-pdf-settings" data-kitgenix-tabs data-kitgenix-default-tab="<?php echo esc_attr( $default_tab ); ?>">

            <div class="kitgenix-topbar">
                <div class="kitgenix-topbar-left">
                    <a class="kitgenix-topbar-brand" href="<?php echo esc_url( admin_url( 'admin.php?page=kitgenix' ) ); ?>" title="Kitgenix">
                        <img class="kitgenix-topbar-logo" src="<?php echo esc_url( ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL' ) ? KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL : plugin_dir_url( __FILE__ ) ) . 'assets/images/logos/kitgenix-primary-favicon.svg' ); ?>" alt="Kitgenix" width="28" height="28" />
                    </a>
                    <span class="kitgenix-topbar-divider" aria-hidden="true"></span>
                    <div class="kitgenix-topbar-plugin-info">
                        <span class="kitgenix-topbar-title"><?php echo esc_html__( 'PDF Invoicing for WooCommerce', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></span>
                        <span class="kitgenix-topbar-version">v<?php echo esc_html( $ver ); ?></span>
                    </div>
                </div>
                <div class="kitgenix-topbar-center">
                    <ul class="kitgenix-topbar-menu" role="tablist" aria-label="<?php echo esc_attr__( 'Navigation', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>">
                        <li class="kitgenix-menu-item <?php echo ( 'settings' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'settings' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=settings#kitgenix-tab-settings' ); ?>" data-kitgenix-tab="settings"><?php echo esc_html__( 'Settings', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                        <li class="kitgenix-menu-item <?php echo ( 'branding' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'branding' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=branding#kitgenix-tab-branding' ); ?>" data-kitgenix-tab="branding"><?php echo esc_html__( 'Brand & Styling', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                        <li class="kitgenix-menu-item <?php echo ( 'emails' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'emails' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=emails#kitgenix-tab-emails' ); ?>" data-kitgenix-tab="emails"><?php echo esc_html__( 'Email Attachments', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                        <li class="kitgenix-menu-item <?php echo ( 'log' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'log' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=log#kitgenix-tab-log' ); ?>" data-kitgenix-tab="log"><?php echo esc_html__( 'Log', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                        <li class="kitgenix-menu-item <?php echo ( 'status' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'status' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=status#kitgenix-tab-status' ); ?>" data-kitgenix-tab="status"><?php echo esc_html__( 'System Status', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                        <li class="kitgenix-menu-item <?php echo ( 'support' === $default_tab ) ? 'kitgenix-active' : ''; ?>"><a class="kitgenix-menu-link <?php echo ( 'support' === $default_tab ) ? 'kitgenix-active' : ''; ?> kitgenix-tab-trigger" href="<?php echo esc_url( $base_tab_url . '&tab=support#kitgenix-tab-support' ); ?>" data-kitgenix-tab="support"><?php echo esc_html__( 'Support', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a></li>
                    </ul>
                </div>
                <div class="kitgenix-topbar-right" aria-label="Topbar actions">
                    <div class="kitgenix-topbar-search">
                        <button type="button" class="kitgenix-topbar-icon-btn kitgenix-search-toggle" aria-label="<?php echo esc_attr__( 'Search settings', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M14.5232 13.4627L17.7355 16.6742L16.6742 17.7355L13.4627 14.5232C12.2678 15.4812 10.7815 16.0022 9.25 16C5.524 16 2.5 12.976 2.5 9.25C2.5 5.524 5.524 2.5 9.25 2.5C12.976 2.5 16 5.524 16 9.25C16.0022 10.7815 15.4812 12.2678 14.5232 13.4627ZM13.0187 12.9062C13.9706 11.9274 14.5021 10.6153 14.5 9.25C14.5 6.349 12.1502 4 9.25 4C6.349 4 4 6.349 4 9.25C4 12.1502 6.349 14.5 9.25 14.5C10.6153 14.5021 11.9274 13.9706 12.9062 13.0187L13.0187 12.9062V12.9062Z" fill="currentColor"></path></svg></button>
                        <div class="kitgenix-search-panel">
                            <span class="kitgenix-search-icon" aria-hidden="true"><svg width="15" height="15" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M14.5232 13.4627L17.7355 16.6742L16.6742 17.7355L13.4627 14.5232C12.2678 15.4812 10.7815 16.0022 9.25 16C5.524 16 2.5 12.976 2.5 9.25C2.5 5.524 5.524 2.5 9.25 2.5C12.976 2.5 16 5.524 16 9.25C16.0022 10.7815 15.4812 12.2678 14.5232 13.4627ZM13.0187 12.9062C13.9706 11.9274 14.5021 10.6153 14.5 9.25C14.5 6.349 12.1502 4 9.25 4C6.349 4 4 6.349 4 9.25C4 12.1502 6.349 14.5 9.25 14.5C10.6153 14.5021 11.9274 13.9706 12.9062 13.0187L13.0187 12.9062V12.9062Z" fill="currentColor"></path></svg></span>
                            <input type="search" class="kitgenix-topbar-search-input" placeholder="<?php echo esc_attr__( 'Search settings…', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" aria-label="<?php echo esc_attr__( 'Search settings', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" autocomplete="off" />
                            <kbd class="kitgenix-search-kbd" title="Press / or ⌘K to search">/</kbd>
                            <button type="button" class="kitgenix-search-clear" aria-label="<?php echo esc_attr__( 'Clear search', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" style="display:none;">&times;</button>
                        </div>
                    </div>
                    <button type="button" class="kitgenix-topbar-icon-btn kitgenix-theme-toggle" aria-label="<?php echo esc_attr__( 'Toggle color theme', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" title="<?php echo esc_attr__( 'Toggle color theme', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>">
                        <svg class="kitgenix-theme-icon-light" width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="10" cy="10" r="3.25" stroke="currentColor" stroke-width="1.3"></circle><path d="M10 2.5v2M10 15.5v2M17.5 10h-2M4.5 10h-2M15.3 4.7l-1.4 1.4M6.1 13.9l-1.4 1.4M15.3 15.3l-1.4-1.4M6.1 6.1 4.7 4.7" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"></path></svg>
                        <svg class="kitgenix-theme-icon-dark" width="16" height="16" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M16.5 12.3A6.5 6.5 0 0 1 7.7 3.5a6.5 6.5 0 1 0 8.8 8.8Z" fill="currentColor"></path></svg>
                    </button>
                    <a class="kitgenix-topbar-icon-btn" href="<?php echo esc_url( admin_url( 'admin.php?page=kitgenix' ) ); ?>" title="<?php echo esc_attr__( 'Kitgenix Hub', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" aria-label="Kitgenix Hub"><svg width="15" height="15" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M3.25 3.25H9.25V9.25H3.25V3.25ZM10.75 3.25H16.75V9.25H10.75V3.25ZM3.25 10.75H9.25V16.75H3.25V10.75ZM10.75 10.75H16.75V16.75H10.75V10.75Z" fill="currentColor"></path></svg></a>
                    <button type="button" class="kitgenix-topbar-hamburger" aria-label="<?php echo esc_attr__( 'Toggle navigation', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>"><span></span><span></span><span></span></button>
                </div>
            </div>

            <div class="kitgenix-settings-layout">
                <div class="kitgenix-settings-content" id="kitgenix-settings-content" tabindex="-1">

            <?php $page = 'kitgenix-pdf-invoicing-settings'; ?>

            <div id="kitgenix-tab-settings" class="kitgenix-tab-panel" data-section data-kitgenix-tab-panel="settings" <?php echo ( 'settings' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <form action="options.php" method="post">
                    <?php
                    settings_fields( 'kitgenix_pdf_invoicing_for_woocommerce_' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_main', 'building' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_numbering', 'hash' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_localization', 'globe' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_fields', 'list' );
                    submit_button();
                    ?>
                </form>
            </div>

            <div id="kitgenix-tab-branding" class="kitgenix-tab-panel" data-section data-kitgenix-tab-panel="branding" <?php echo ( 'branding' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <form action="options.php" method="post">
                    <?php
                    settings_fields( 'kitgenix_pdf_invoicing_for_woocommerce_' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_brand', 'palette' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_designer', 'brush' );
                    submit_button();
                    ?>
                </form>

                <?php $this->render_font_management_tools(); ?>
            </div>

            <div id="kitgenix-tab-emails" class="kitgenix-tab-panel" data-section data-kitgenix-tab-panel="emails" <?php echo ( 'emails' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <form action="options.php" method="post">
                    <?php
                    settings_fields( 'kitgenix_pdf_invoicing_for_woocommerce_' );
                    $this->render_section_card( $page, 'kitgenix_pdf_invoicing_email', 'mail' );
                    submit_button();
                    ?>
                </form>

                <?php $this->render_email_test_tools(); ?>
            </div>

            <div id="kitgenix-tab-support" class="kitgenix-tab-panel kitgenix-support-page" data-section data-kitgenix-tab-panel="support" <?php echo ( 'support' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <?php
                $kitgenix_pdf_invoicing_for_woocommerce_donate_url      = 'https://www.paypal.com/donate/?hosted_button_id=KALF36K6JJ9B2';
                $kitgenix_pdf_invoicing_for_woocommerce_plugin_page_url = 'https://kitgenix.com/plugins/kitgenix-pdf-invoicing-for-woocommerce/';
                $kitgenix_pdf_invoicing_for_woocommerce_review_url      = 'https://wordpress.org/support/plugin/kitgenix-pdf-invoicing-for-woocommerce/reviews/#new-post';
                $kitgenix_pdf_invoicing_for_woocommerce_docs_url        = 'https://kitgenix.com/plugins/kitgenix-pdf-invoicing-for-woocommerce/documentation/';
                $kitgenix_pdf_invoicing_for_woocommerce_copy_onclick    = "if(window.navigator&&navigator.clipboard&&window.isSecureContext){navigator.clipboard.writeText(" . wp_json_encode( $kitgenix_pdf_invoicing_for_woocommerce_plugin_page_url ) . ");}else{window.prompt(" . wp_json_encode( __( 'Copy plugin link:', 'kitgenix-pdf-invoicing-for-woocommerce' ) ) . ", " . wp_json_encode( $kitgenix_pdf_invoicing_for_woocommerce_plugin_page_url ) . ");}return false;";
                ?>
                <div class="kitgenix-pdf-invoicing-for-woocommerce-support-page kitgenix-support-page">
                    <div class="kitgenix-card kitgenix-support-hero">
                        <div class="kitgenix-support-hero-inner">
                            <span class="kitgenix-support-hero-icon" aria-hidden="true"><?php echo $this->icon( 'heart' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?></span>
                            <p class="kitgenix-support-hero-eyebrow"><?php esc_html_e( 'Support Kitgenix', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                            <h2><?php esc_html_e( 'Help us keep building', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                            <p class="kitgenix-support-hero-body"><?php esc_html_e( 'This plugin turns every WooCommerce order into an invoice, receipt, packing slip, or credit note automatically, with no locked "pro" tier. A donation is what pays for the time to keep it working through every new WooCommerce release and to answer support requests.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                            <a class="kitgenix-support-hero-button" href="<?php echo esc_url( $kitgenix_pdf_invoicing_for_woocommerce_donate_url ); ?>" target="_blank" rel="noopener noreferrer">
                                <?php echo $this->icon( 'paypal' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?>
                                <?php esc_html_e( 'Donate with PayPal', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                            </a>
                            <p class="kitgenix-support-hero-caption">
                                <?php echo $this->icon( 'shield' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?>
                                <?php esc_html_e( 'Donations are entirely optional. Kitgenix plugins keep working whether you donate or not.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                            </p>
                        </div>

                        <div class="kitgenix-support-links">
                            <a class="kitgenix-support-link" href="<?php echo esc_url( $kitgenix_pdf_invoicing_for_woocommerce_review_url ); ?>" target="_blank" rel="noopener noreferrer">
                                <?php echo $this->icon( 'star' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?>
                                <?php esc_html_e( 'Leave a review', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                            </a>
                            <a class="kitgenix-support-link" href="<?php echo esc_url( $kitgenix_pdf_invoicing_for_woocommerce_docs_url ); ?>" target="_blank" rel="noopener noreferrer">
                                <?php echo $this->icon( 'logs' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?>
                                <?php esc_html_e( 'Read the docs', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                            </a>
                            <button type="button" class="kitgenix-support-link" onclick="<?php echo esc_attr( $kitgenix_pdf_invoicing_for_woocommerce_copy_onclick ); ?>">
                                <?php echo $this->icon( 'copy' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?>
                                <?php esc_html_e( 'Copy plugin link', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>
                            </button>
                        </div>
                    </div>
                </div>
            </div>

            <div id="kitgenix-tab-log" class="kitgenix-tab-panel" data-section data-kitgenix-tab-panel="log" <?php echo ( 'log' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <?php $this->render_log_tab(); ?>
            </div>

            <div id="kitgenix-tab-status" class="kitgenix-tab-panel" data-section data-kitgenix-tab-panel="status" <?php echo ( 'status' !== $default_tab ) ? 'hidden="hidden" style="display:none" aria-hidden="true"' : 'aria-hidden="false"'; ?>>
                <?php $this->render_status_tab(); ?>
            </div>

                </div>
                <?php $this->render_sidebar(); ?>
            </div>
        </div>
        <?php
    }

    private function render_sidebar(): void {
        $social_base = ( defined( 'KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL' ) ? (string) KITGENIX_PDF_INVOICING_FOR_WOOCOMMERCE_URL : plugin_dir_url( __FILE__ ) ) . 'assets/images/social-media/';
        ?>
        <aside class="kitgenix-settings-sidebar" aria-label="<?php echo esc_attr__( 'Help and links', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>">
            <div class="kitgenix-card">
                <div class="kitgenix-card-body">
                    <h2><?php echo esc_html__( 'Need Help?', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php echo esc_html__( 'Open the documentation for setup guidance or send us a support request if you need help configuring the plugin.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                    <div class="kitgenix-button-group kitgenix-button-group-stack">
                        <a class="button button-secondary" href="<?php echo esc_url( 'https://kitgenix.com/plugins/kitgenix-pdf-invoicing-for-woocommerce/documentation/' ); ?>" target="_blank" rel="noopener noreferrer"><?php echo esc_html__( 'Documentation', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                        <a class="button button-primary" href="<?php echo esc_url( 'https://kitgenix.com/plugins/kitgenix-pdf-invoicing-for-woocommerce/support' ); ?>" target="_blank" rel="noopener noreferrer"><?php echo esc_html__( 'Request Support', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                    </div>
                </div>
            </div>

            <div class="kitgenix-card">
                <div class="kitgenix-card-body">
                    <h2><?php echo esc_html__( 'Visit Our Official Facebook Group', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php echo esc_html__( 'Join the Kitgenix community to ask questions, share feedback, and keep up with product updates.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                    <div class="kitgenix-button-group kitgenix-button-group-stack">
                        <a class="button button-secondary" href="<?php echo esc_url( 'https://www.facebook.com/groups/kitgenix' ); ?>" target="_blank" rel="noopener noreferrer"><?php echo esc_html__( 'Join Group', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                    </div>
                </div>
            </div>

            <div class="kitgenix-card">
                <div class="kitgenix-card-body">
                    <h2><?php echo esc_html__( 'Follow Us', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php echo esc_html__( 'Keep up with new releases, tutorials, and product news across our channels.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                    <div class="kitgenix-sidebar-social-grid">
                        <a class="kitgenix-sidebar-social-link" href="https://kitgenix.com" target="_blank" rel="noopener noreferrer" aria-label="Website" title="Website"><img src="<?php echo esc_url( $social_base . 'globe-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.facebook.com/kitgenix" target="_blank" rel="noopener noreferrer" aria-label="Facebook" title="Facebook"><img src="<?php echo esc_url( $social_base . 'facebook-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.instagram.com/kitgenix/" target="_blank" rel="noopener noreferrer" aria-label="Instagram" title="Instagram"><img src="<?php echo esc_url( $social_base . 'instagram-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.youtube.com/@Kitgenix" target="_blank" rel="noopener noreferrer" aria-label="YouTube" title="YouTube"><img src="<?php echo esc_url( $social_base . 'youtube-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.reddit.com/r/Kitgenix/" target="_blank" rel="noopener noreferrer" aria-label="Reddit" title="Reddit"><img src="<?php echo esc_url( $social_base . 'reddit-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.linkedin.com/company/kitgenix" target="_blank" rel="noopener noreferrer" aria-label="LinkedIn" title="LinkedIn"><img src="<?php echo esc_url( $social_base . 'linkedin-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://x.com/kitgenix" target="_blank" rel="noopener noreferrer" aria-label="X" title="X"><img src="<?php echo esc_url( $social_base . 'x-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://www.tiktok.com/@kitgenix" target="_blank" rel="noopener noreferrer" aria-label="TikTok" title="TikTok"><img src="<?php echo esc_url( $social_base . 'tiktok-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                        <a class="kitgenix-sidebar-social-link" href="https://github.com/kitgenix" target="_blank" rel="noopener noreferrer" aria-label="GitHub" title="GitHub"><img src="<?php echo esc_url( $social_base . 'github-solid.svg' ); ?>" alt="" width="16" height="16" aria-hidden="true" /></a>
                    </div>
                </div>
            </div>
        </aside>
        <?php
    }

    private function render_log_tab(): void {
        $log_cleared = false;
        // phpcs:ignore WordPress.Security.NonceVerification.Recommended
        if ( isset( $_GET['kitgenix_log_cleared'] ) ) {
            $log_cleared = true;
        }

        $clear_url = wp_nonce_url(
            admin_url( 'admin-post.php?action=kitgenix_pdf_invoicing_clear_event_log' ),
            'kitgenix_pdf_invoicing_clear_event_log'
        );

        $log_entries = Event_Log::get_raw_log();
        $date_format = (string) get_option( 'date_format' ) . ' ' . (string) get_option( 'time_format' );

        $outcome_badge = static function ( string $outcome ): string {
            $outcome_l = strtolower( $outcome );
            if ( 'error' === $outcome_l || 'failed' === $outcome_l || 'failure' === $outcome_l ) {
                return 'danger';
            }
            if ( 0 === strpos( $outcome_l, 'warn' ) ) {
                return 'warning';
            }
            if ( 'success' === $outcome_l || 'ok' === $outcome_l ) {
                return 'success';
            }
            return 'neutral';
        };
        ?>
        <?php if ( $log_cleared ) : ?>
            <div class="kitgenix-notice kitgenix-notice-success" role="status">
                <div class="kitgenix-notice-body">
                    <p class="kitgenix-notice-text"><?php esc_html_e( 'Event log cleared.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
                <button type="button" class="kitgenix-notice-close" aria-label="<?php echo esc_attr__( 'Dismiss', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>">&times;</button>
            </div>
        <?php endif; ?>

        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div>
                    <h2 class="kitgenix-support-subheading"><?php esc_html_e( 'Activity Log', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p class="description"><?php esc_html_e( 'A record of recent plugin events. Entries show the timestamp, context, outcome, and a plain-English note. IP addresses and sensitive data are never stored here.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
                <div class="kitgenix-card-head-actions">
                    <a href="<?php echo esc_url( $clear_url ); ?>" class="button button-secondary" onclick="return confirm('<?php echo esc_js( __( 'Clear all log entries?', 'kitgenix-pdf-invoicing-for-woocommerce' ) ); ?>')"><?php esc_html_e( 'Clear log', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></a>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <?php if ( empty( $log_entries ) ) : ?>
                    <div class="kitgenix-empty-state">
                        <span class="kitgenix-empty-state-icon" aria-hidden="true"><?php echo $this->icon( 'activity' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?></span>
                        <h3 class="kitgenix-empty-state-title"><?php esc_html_e( 'No events logged yet', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h3>
                        <p class="kitgenix-empty-state-desc"><?php esc_html_e( 'Activity will appear here as it happens.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                    </div>
                <?php else : ?>
                    <div class="kitgenix-search-bar">
                        <div class="kitgenix-search-bar-input">
                            <span class="kitgenix-search-bar-icon" aria-hidden="true"><?php echo $this->icon( 'search' ); /* phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- static trusted SVG from icon(). */ ?></span>
                            <input type="search" placeholder="<?php echo esc_attr__( 'Search log…', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?>" data-kitgenix-table-search data-kitgenix-table-search-target="#kitgenix-pdf-invoicing-log-table" />
                        </div>
                    </div>
                    <div class="kitgenix-table-wrap" id="kitgenix-pdf-invoicing-log-table" data-kitgenix-table-paginate="25">
                        <table class="kitgenix-table">
                            <thead>
                                <tr>
                                    <th><?php esc_html_e( 'Time', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                    <th><?php esc_html_e( 'Context', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                    <th><?php esc_html_e( 'Outcome', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                    <th><?php esc_html_e( 'Note', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                                </tr>
                            </thead>
                            <tbody>
                                <?php foreach ( array_reverse( $log_entries ) as $entry ) : ?>
                                    <?php
                                    $entry_time    = isset( $entry['time'] ) ? (int) $entry['time'] : 0;
                                    $entry_context = (string) ( $entry['context'] ?? '' );
                                    $entry_outcome = (string) ( $entry['outcome'] ?? '' );
                                    $entry_note    = (string) ( $entry['note'] ?? '' );
                                    $entry_when    = $entry_time ? (string) wp_date( $date_format, $entry_time ) : __( 'Unknown time', 'kitgenix-pdf-invoicing-for-woocommerce' );
                                    ?>
                                    <tr data-kitgenix-table-row>
                                        <td><?php echo esc_html( $entry_when ); ?></td>
                                        <td><code><?php echo esc_html( $entry_context ); ?></code></td>
                                        <td><span class="kitgenix-badge <?php echo esc_attr( $outcome_badge( $entry_outcome ) ); ?>"><?php echo esc_html( $entry_outcome ); ?></span></td>
                                        <td><?php echo esc_html( $entry_note ); ?></td>
                                    </tr>
                                <?php endforeach; ?>
                            </tbody>
                        </table>
                        <div class="kitgenix-empty-state" data-kitgenix-table-empty style="display:none;">
                            <p class="kitgenix-empty-state-title"><?php esc_html_e( 'No matching log entries', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                        </div>
                    </div>
                <?php endif; ?>
            </div>
        </div>

        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div>
                    <h2 class="kitgenix-support-subheading"><?php esc_html_e( 'Understanding log entries', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p class="description"><?php esc_html_e( 'Some events below are genuine problems that need attention; others are expected skips or likely false positives that usually need no action.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <div class="kitgenix-table-wrap"><table class="kitgenix-table">
                    <thead>
                        <tr>
                            <th><?php esc_html_e( 'Category', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                            <th><?php esc_html_e( 'What it means', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                            <th><?php esc_html_e( 'Action needed?', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td><code>settings-saved</code></td>
                            <td><?php esc_html_e( 'Plugin settings were updated by an administrator.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'None.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>render-error</code></td>
                            <td><?php esc_html_e( 'The PDF renderer failed unexpectedly while generating a document.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'Check the note for the underlying error. If it repeats for the same order, the order content or a custom template may be malformed.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>resource-limit</code></td>
                            <td><?php esc_html_e( 'PDF generation hit a PHP memory or time limit while rendering the document.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'Usually a false positive – likely just a very large order, not necessarily a bug. If it repeats, raise your host\'s PHP memory_limit and max_execution_time.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>storage-error</code></td>
                            <td><?php esc_html_e( 'The plugin could not resolve, create, or write to its archive storage folder in your WordPress uploads directory.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'Check disk space and file system permissions on the uploads directory.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>email-attachment-missing</code></td>
                            <td><?php esc_html_e( 'A WooCommerce email was sent without its PDF attachment because the document could not be generated.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'The customer or admin did not receive their document. Check the log around the same time for the underlying PDF generation error.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>generation-failed</code></td>
                            <td><?php esc_html_e( 'A PDF could not be generated for an order during a bulk (batch) operation.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'Check the log around the same time for the underlying render or storage error.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>order-not-found</code></td>
                            <td><?php esc_html_e( 'An order selected for a bulk operation no longer exists (it may have been deleted).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'None – the order was skipped automatically. Expected behavior.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                        <tr>
                            <td><code>not-eligible</code></td>
                            <td><?php esc_html_e( 'An order was skipped because the requested document type does not apply to it (for example, a credit note with no refunds).', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                            <td><?php esc_html_e( 'None. Expected behavior – no action needed.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></td>
                        </tr>
                    </tbody>
                </table></div>
            </div>
        </div>
        <?php
    }

    private function render_status_tab(): void {
        $report = SystemStatus::get_report();

        $section_titles = [
            'environment' => __( 'Environment', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'php_limits'  => __( 'PHP Limits', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'storage'     => __( 'Storage', 'kitgenix-pdf-invoicing-for-woocommerce' ),
            'template'    => __( 'Template & Numbering', 'kitgenix-pdf-invoicing-for-woocommerce' ),
        ];

        /* phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only UI notice flag, no state change performed here. */
        $imported = isset( $_GET['kitgenix_settings_imported'] ) ? sanitize_key( wp_unslash( $_GET['kitgenix_settings_imported'] ) ) : '';
        ?>
        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div class="kitgenix-card-head-text">
                    <h2><?php esc_html_e( 'System Status', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php esc_html_e( 'Environment diagnostics for support requests. No customer data or secrets are shown here.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <?php foreach ( $report as $section => $rows ) : ?>
                    <div class="kitgenix-status-section">
                        <h3 class="kitgenix-status-section-title"><?php echo esc_html( $section_titles[ $section ] ?? ucfirst( $section ) ); ?></h3>
                        <div class="kitgenix-table-wrap">
                            <table class="kitgenix-table kitgenix-status-table">
                                <tbody>
                                    <?php foreach ( $rows as $label => $value ) : ?>
                                        <tr>
                                            <th scope="row"><?php echo esc_html( $label ); ?></th>
                                            <td><?php echo esc_html( $value ); ?></td>
                                        </tr>
                                    <?php endforeach; ?>
                                </tbody>
                            </table>
                        </div>
                    </div>
                <?php endforeach; ?>
            </div>
        </div>

        <div class="kitgenix-card">
            <div class="kitgenix-card-head">
                <div class="kitgenix-card-head-text">
                    <h2><?php esc_html_e( 'Settings Import / Export', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></h2>
                    <p><?php esc_html_e( 'Move plugin settings between sites (e.g. staging to production). The exported file never includes your logo attachment ID, since media IDs are not portable between sites – re-select your logo after importing.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p>
                </div>
            </div>
            <div class="kitgenix-card-body">
                <?php if ( 'ok' === $imported ) : ?>
                    <div class="notice notice-success inline"><p><?php esc_html_e( 'Settings imported successfully.', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></p></div>
                <?php endif; ?>

                <form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
                    <input type="hidden" name="action" value="kitgenix_pdf_invoicing_export_settings" />
                    <?php wp_nonce_field( 'kitgenix_pdf_invoicing_export_settings' ); ?>
                    <button type="submit" class="button button-secondary"><?php esc_html_e( 'Download settings (.json)', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></button>
                </form>

                <form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" enctype="multipart/form-data" style="margin-top:16px;">
                    <input type="hidden" name="action" value="kitgenix_pdf_invoicing_import_settings" />
                    <?php wp_nonce_field( 'kitgenix_pdf_invoicing_import_settings' ); ?>
                    <p>
                        <label for="kitgenix_settings_import_file"><?php esc_html_e( 'Import settings file (.json)', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></label><br />
                        <input type="file" name="kitgenix_settings_import_file" id="kitgenix_settings_import_file" accept="application/json,.json" required />
                    </p>
                    <button type="submit" class="button button-primary" onclick="return confirm('<?php echo esc_js( __( 'Import will overwrite matching settings on this site. Continue?', 'kitgenix-pdf-invoicing-for-woocommerce' ) ); ?>');"><?php esc_html_e( 'Import settings', 'kitgenix-pdf-invoicing-for-woocommerce' ); ?></button>
                </form>
            </div>
        </div>
        <?php
    }

    public function handle_export_settings(): void {
        if ( ! current_user_can( 'manage_woocommerce' ) ) {
            wp_die( esc_html__( 'Permission denied.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 403 );
        }
        check_admin_referer( 'kitgenix_pdf_invoicing_export_settings' );

        $json     = SettingsTransfer::export_json();
        $filename = 'kitgenix-pdf-invoicing-settings-' . gmdate( 'Ymd-His' ) . '.json';

        nocache_headers();
        header( 'Content-Type: application/json; charset=utf-8' );
        header( 'Content-Disposition: attachment; filename="' . sanitize_file_name( $filename ) . '"' );
        header( 'Content-Length: ' . strlen( $json ) );
        echo $json; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- JSON export, not HTML.
        exit;
    }

    public function handle_import_settings(): void {
        if ( ! current_user_can( 'manage_woocommerce' ) ) {
            wp_die( esc_html__( 'Permission denied.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 403 );
        }
        check_admin_referer( 'kitgenix_pdf_invoicing_import_settings' );

        // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- $_FILES[...]['tmp_name'] is a PHP-generated temp path, not free-text input; validated below via is_uploaded_file().
        if ( empty( $_FILES['kitgenix_settings_import_file']['tmp_name'] ) || ! is_uploaded_file( $_FILES['kitgenix_settings_import_file']['tmp_name'] ) ) {
            add_settings_error( Settings::OPTION_KEY, 'kitgenix_import_no_file', __( 'Choose a settings JSON file to import.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 'error' );
            set_transient( 'settings_errors', get_settings_errors(), 30 );
            wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=status' ) );
            exit;
        }

        global $wp_filesystem;
        if ( empty( $wp_filesystem ) ) {
            require_once ABSPATH . 'wp-admin/includes/file.php';
            WP_Filesystem();
        }
        // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- $_FILES[...]['tmp_name'] is a PHP-generated temp path, not free-text input; already validated above via is_uploaded_file().
        $contents = $wp_filesystem->get_contents( $_FILES['kitgenix_settings_import_file']['tmp_name'] );
        $result   = SettingsTransfer::import_json( is_string( $contents ) ? $contents : '' );

        if ( is_wp_error( $result ) ) {
            add_settings_error( Settings::OPTION_KEY, 'kitgenix_import_failed', $result->get_error_message(), 'error' );
            set_transient( 'settings_errors', get_settings_errors(), 30 );
            wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=status' ) );
            exit;
        }

        Event_Log::record( 'settings-imported', 'success', __( 'Plugin settings were imported from a JSON file.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 'settings-saved' );

        wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=status&kitgenix_settings_imported=ok' ) );
        exit;
    }

    public function handle_upload_font(): void {
        if ( ! current_user_can( 'manage_woocommerce' ) ) {
            wp_die( esc_html__( 'Permission denied.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 403 );
        }
        check_admin_referer( 'kitgenix_pdf_invoicing_upload_font' );

        $family = isset( $_POST['font_family'] ) ? sanitize_text_field( wp_unslash( $_POST['font_family'] ) ) : '';
        $file   = isset( $_FILES['font_file'] ) ? $_FILES['font_file'] : []; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput -- validated inside FontManager::handle_upload() (signature/extension/size checks), not used directly here.

        $result = \Kitgenix\PDF_Invoicing\Modules\Invoicing\FontManager::handle_upload( is_array( $file ) ? $file : [], $family );

        if ( is_wp_error( $result ) ) {
            add_settings_error( Settings::OPTION_KEY, 'kitgenix_font_upload_failed', $result->get_error_message(), 'error' );
        } else {
            add_settings_error( Settings::OPTION_KEY, 'kitgenix_font_upload_ok', sprintf(
                /* translators: %s: font family name. */
                __( 'Font "%s" uploaded. Select it from the Document font dropdown and save.', 'kitgenix-pdf-invoicing-for-woocommerce' ),
                $result
            ), 'updated' );
        }

        set_transient( 'settings_errors', get_settings_errors(), 30 );
        wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=branding' ) );
        exit;
    }

    public function handle_delete_font(): void {
        if ( ! current_user_can( 'manage_woocommerce' ) ) {
            wp_die( esc_html__( 'Permission denied.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 403 );
        }
        check_admin_referer( 'kitgenix_pdf_invoicing_delete_font' );

        $font_key = isset( $_GET['font_key'] ) ? sanitize_key( wp_unslash( $_GET['font_key'] ) ) : '';
        if ( '' !== $font_key ) {
            \Kitgenix\PDF_Invoicing\Modules\Invoicing\FontManager::delete_font( $font_key );
        }

        wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=branding' ) );
        exit;
    }

    public function handle_clear_event_log(): void {
        if ( ! current_user_can( 'manage_options' ) ) {
            wp_die( esc_html__( 'Permission denied.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 403 );
        }
        check_admin_referer( 'kitgenix_pdf_invoicing_clear_event_log' );
        Event_Log::clear();
        wp_safe_redirect( admin_url( 'admin.php?page=kitgenix-pdf-invoicing-settings&tab=log&kitgenix_log_cleared=1' ) );
        exit;
    }

    public function on_settings_saved( mixed $old_value, mixed $new_value, string $option ): void {
        Event_Log::record( 'settings-saved', 'success', __( 'Plugin settings were saved via the admin settings page.', 'kitgenix-pdf-invoicing-for-woocommerce' ), 'settings-saved' );
    }
}
