<?php
/**
 * Unified admin header — same shape as Flow/Velocity/Draft Forge, GuardForge
 * accent (see ADMIN-HEADER-SPEC.md, forge/paused/revival-2026-09-03/).
 *
 * One render call replaces the old per-partial "heading + letter mark"
 * block. Every screen keeps exactly one top-level heading, printed here —
 * see plugin/tests/class-admin-header-surface-test.php for the invariant
 * that guarantees it holds for every partial.
 *
 * Nothing about licences lives here (wp.org Guideline 5). Until 1.5.0 this
 * class drew a plan badge, a credits chip and a trial / renew button; since
 * 1.6.0 those belong to GuardForge Pro, which fills the two hooks render
 * fires on either side of the Docs link. Without the add-on the row holds
 * the Docs link alone.
 */

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

class GUARDFORGE_Admin_Header {

    const SLUG = 'guardforge';

    /**
 * Page links for a log table, because a LIMIT/OFFSET query with no pager
 * strands every row past the first page where nobody can reach it.
 *
 * @param int $paged Page currently being drawn, 1-based.
 * @param int $pages Total number of pages the filter matches.
 * @param string $query_arg Query variable that carries the page number.
 * @return string Ready-to-echo markup, or '' when it all fits on one page.
 */
    /**
 * What our own admin markup may carry through wp_kses on the way out.
 *
 * The wp.org review of 23.09.2026 asked for escaping at the point of echo,
 * including for markup our own helpers build. esc_html would print the
 * tags, so the escape here is a kses pass over a list that covers exactly
 * what those helpers emit — the round-trip tests in
 * tests/class-escaped-output-test.php fail the moment one emits anything
 * else, which is the failure mode this list is for.
 *
 * @return array<string,array<string,bool>>
 */
    public static function allowed_markup() {
        $common  = [
            'id' => true, 'class' => true, 'style' => true, 'title' => true,
            'role' => true, 'hidden' => true, 'data-*' => true, 'aria-*' => true,
        ];
        $allowed = wp_kses_allowed_html( 'post' );

        $allowed['form']     = array_merge( $common, [ 'method' => true, 'action' => true, 'target' => true ] );
        $allowed['input']    = array_merge( $common, [
            'type' => true, 'name' => true, 'value' => true, 'checked' => true, 'placeholder' => true,
            'min' => true, 'max' => true, 'step' => true, 'required' => true, 'readonly' => true,
            'disabled' => true, 'autocomplete' => true, 'pattern' => true, 'inputmode' => true,
        ] );
        $allowed['select']   = array_merge( $common, [ 'name' => true, 'multiple' => true, 'disabled' => true ] );
        $allowed['option']   = array_merge( $common, [ 'value' => true, 'selected' => true, 'disabled' => true ] );
        $allowed['textarea'] = array_merge( $common, [ 'name' => true, 'rows' => true, 'cols' => true, 'placeholder' => true ] );
        $allowed['button']   = array_merge( $common, [ 'type' => true, 'name' => true, 'value' => true, 'disabled' => true ] );
        $allowed['label']    = array_merge( $common, [ 'for' => true ] );
        $allowed['details']  = array_merge( $common, [ 'open' => true ] );
        $allowed['summary']  = $common;
        $allowed['template'] = $common;

        return array_merge( $allowed, self::allowed_svg() );
    }

    /**
 * The same, for SVG drawn INSIDE an HTML page — the QR code and the logo.
 *
 * Not for an SVG served as its own image/svg+xml document: there the file
 * is parsed as XML, where kses lowercasing viewBox would break it. The one
 * such document this plugin serves (the score badge) is built from a band
 * letter and a YYYY-MM string and is sent with its own restrictive CSP.
 *
 * @return array<string,array<string,bool>>
 */
    public static function allowed_svg() {
        // aria-label by name as well as by wildcard: core's kses honours the
        // data-* wildcard but drops aria-* unless the attribute is named, and
        // the QR code's label is the only thing a screen reader has of it.
        $common = [
            'id' => true, 'class' => true, 'style' => true, 'role' => true,
            'aria-label' => true, 'aria-hidden' => true, 'aria-*' => true, 'data-*' => true,
        ];

        return [
            'svg'   => array_merge( $common, [
                'xmlns' => true, 'viewbox' => true, 'width' => true, 'height' => true,
                'fill' => true, 'stroke' => true, 'preserveaspectratio' => true, 'focusable' => true,
                'shape-rendering' => true, 'image-rendering' => true, 'transform' => true,
            ] ),
            'g'     => array_merge( $common, [ 'fill' => true, 'stroke' => true, 'transform' => true ] ),
            'path'  => array_merge( $common, [ 'd' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true, 'fill-rule' => true, 'clip-rule' => true ] ),
            'rect'  => array_merge( $common, [ 'x' => true, 'y' => true, 'width' => true, 'height' => true, 'rx' => true, 'ry' => true, 'fill' => true, 'stroke' => true, 'shape-rendering' => true ] ),
            'text'  => array_merge( $common, [ 'x' => true, 'y' => true, 'fill' => true, 'font-family' => true, 'font-size' => true, 'font-weight' => true, 'text-anchor' => true, 'dominant-baseline' => true ] ),
            'title' => $common,
            'desc'  => $common,
            'img'   => array_merge( $common, [ 'src' => true, 'alt' => true, 'width' => true, 'height' => true, 'loading' => true ] ),
        ];
    }

    public static function pager( $paged, $pages, $query_arg ) {
        $pages = (int) $pages;
        if ( $pages < 2 ) {
            return '';
        }
        // A hand-typed ?lpaged=999 must still be able to walk back, so the
        // link targets are computed from a clamped page number, not the raw one.
        $paged = min( max( 1, (int) $paged ), $pages );

        $out = '<div class="gf-pager" style="display:flex;gap:8px;align-items:center;justify-content:flex-end;margin-top:12px">';

        if ( $paged > 1 ) {
            $out .= '<a class="button" href="' . esc_url( add_query_arg( $query_arg, $paged - 1 ) ) . '">'
                . esc_html__( 'Previous page', 'guardforge' ) . '</a>';
        }

        /* translators: 1: page currently shown, 2: total number of pages. */
        $out .= '<span class="gf-pager-count">' . esc_html( sprintf( __( 'Page %1$d of %2$d', 'guardforge' ), $paged, $pages ) ) . '</span>';

        if ( $paged < $pages ) {
            $out .= '<a class="button" href="' . esc_url( add_query_arg( $query_arg, $paged + 1 ) ) . '">'
                . esc_html__( 'Next page', 'guardforge' ) . '</a>';
        }

        return $out . '</div>';
    }

    /**
 * Render the header for one admin screen.
 *
 * @param string $title Screen title — the page's one top-level heading.
 * @param string $subtitle Optional one-line description under the title.
 */
    public static function render( $title, $subtitle = '' ) {
        echo '<header class="forge-admin-header forge-admin-header--' . esc_attr( self::SLUG ) . '" data-product="' . esc_attr( self::SLUG ) . '">';

        echo '<div class="forge-admin-header__brand">';
        echo wp_kses( self::logo_markup(), self::allowed_markup() );
        echo '<div class="forge-admin-header__titles">';
        echo '<div class="forge-admin-header__product">' . esc_html( self::product_name() )
            . ' <span class="forge-admin-header__version">v' . esc_html( defined( 'GUARDFORGE_VERSION' ) ? GUARDFORGE_VERSION : '' ) . '</span></div>';
        echo '<h1 class="forge-admin-header__screen">' . esc_html( $title );
        if ( $subtitle !== '' ) {
            echo ' <small>' . esc_html( $subtitle ) . '</small>';
        }
        echo '</h1>';
        echo '</div>'; // titles
        echo '</div>'; // brand

        echo '<div class="forge-admin-header__meta">';
        // The Pro add-on prints its plan and credits here; this package has neither.
        do_action( 'guardforge/admin_header_meta' );
        self::render_docs_link();
        // The add-on's trial / renew button goes last in the row, after Docs,
        // as it did before the licence layer moved out; a second hook, because
        // the first one sits ahead of the link.
        do_action( 'guardforge/admin_header_actions' );
        echo '</div>'; // meta

        echo '</header>';
        echo '<hr class="wp-header-end">';
    }

    /**
 * "Guard Forge" — from the shared suite registry (call only, never
 * edit — includes/class-forge-suite-registry.php is byte-identical
 * across all eight products) when it happens to be loaded, else the
 * literal every other GuardForge string already carries.
 */
    private static function product_name() {
        if ( class_exists( 'Forge_Suite_Registry' ) ) {
            $tool = Forge_Suite_Registry::tool( self::SLUG );
            if ( is_array( $tool ) && ! empty( $tool['name'] ) ) {
                return (string) $tool['name'];
            }
        }
        return __( 'Guard Forge', 'guardforge' );
    }

    /**
 * The real product mark, in priority order:
 * 1. Forge_Suite_Dashboard::LOGOS_B64[slug] via ::logo_img — the
 * shared dashboard class (call only, never edit).
 * 2. This plugin's own assets/logo.svg.
 * 3. A letter fallback, same visual slot either way.
 */
    private static function logo_markup() {
        if ( class_exists( 'Forge_Suite_Dashboard' ) ) {
            $html = Forge_Suite_Dashboard::logo_img( self::SLUG, 'forge-admin-header__mark' );
            if ( $html !== '' ) {
                return method_exists( 'Forge_Suite_Dashboard', 'kses_logo' )
                    ? Forge_Suite_Dashboard::kses_logo( $html )
                    : $html;
            }
        }

        if ( defined( 'GUARDFORGE_DIR' ) && defined( 'GUARDFORGE_URL' ) && is_readable( GUARDFORGE_DIR . 'assets/logo.svg' ) ) {
            return '<img class="forge-admin-header__mark" src="' . esc_url( GUARDFORGE_URL . 'assets/logo.svg' ) . '" alt="" width="36" height="36">';
        }

        return '<span class="forge-admin-header__mark forge-admin-header__mark--letter" aria-hidden="true">G</span>';
    }

    /** Docs link — the plugin's own existing docs URL constant, no new one. */
    private static function render_docs_link() {
        $url = defined( 'FORGE_DOCS_GUARDFORGE' ) ? FORGE_DOCS_GUARDFORGE : '';
        if ( $url === '' ) {
            return;
        }
        echo '<a class="forge-admin-header__docs" href="' . esc_url( $url ) . '" target="_blank" rel="noopener">' . esc_html__( 'Docs', 'guardforge' ) . '</a>';
    }
}