<?php
/**
 * Heading Structure Helper
 * Ensures proper H1-H6 hierarchy for SEO
 * Place in: /helpers/heading_helper.php
 */

class HeadingHelper {
    
    /**
     * Generate H1 heading (one per page)
     */
    public static function h1($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h1' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h1>';
    }
    
    /**
     * Generate H2 heading (section headers)
     */
    public static function h2($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h2' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h2>';
    }
    
    /**
     * Generate H3 heading (subsections)
     */
    public static function h3($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h3' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h3>';
    }
    
    /**
     * Generate H4 heading (sub-subsections)
     */
    public static function h4($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h4' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h4>';
    }
    
    /**
     * Generate H5 heading
     */
    public static function h5($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h5' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h5>';
    }
    
    /**
     * Generate H6 heading
     */
    public static function h6($text, $class = '', $id = '') {
        $classAttr = $class ? ' class="' . htmlspecialchars($class) . '"' : '';
        $idAttr = $id ? ' id="' . htmlspecialchars($id) . '"' : '';
        
        return '<h6' . $classAttr . $idAttr . '>' . htmlspecialchars($text) . '</h6>';
    }
    
    /**
     * Create heading with anchor link
     */
    public static function headingWithAnchor($level, $text, $anchorId = '') {
        if (!$anchorId) {
            $anchorId = str_replace([' ', '/'], ['-', ''], strtolower($text));
        }
        
        $heading = match($level) {
            1 => self::h1($text, '', $anchorId),
            2 => self::h2($text, '', $anchorId),
            3 => self::h3($text, '', $anchorId),
            4 => self::h4($text, '', $anchorId),
            5 => self::h5($text, '', $anchorId),
            6 => self::h6($text, '', $anchorId),
            default => self::h2($text, '', $anchorId)
        };
        
        return $heading;
    }
    
    /**
     * Generate table of contents from headings
     */
    public static function generateTableOfContents($headings = []) {
        if (empty($headings)) {
            return '';
        }
        
        $html = '<nav class="table-of-contents">' . "\n";
        $html .= '<h2>Table of Contents</h2>' . "\n";
        $html .= '<ul>' . "\n";
        
        foreach ($headings as $heading) {
            $level = isset($heading['level']) ? intval($heading['level']) : 2;
            $indent = str_repeat('  ', max(0, $level - 2));
            $link = isset($heading['id']) ? '#' . htmlspecialchars($heading['id']) : '#';
            
            $html .= $indent . '<li><a href="' . $link . '">' . 
                     htmlspecialchars($heading['text']) . '</a></li>' . "\n";
        }
        
        $html .= '</ul>' . "\n";
        $html .= '</nav>' . "\n";
        
        return $html;
    }
    
    /**
     * Validate heading structure
     * Returns array of issues if any
     */
    public static function validateStructure($html) {
        $issues = [];
        
        // Extract all headings from HTML
        preg_match_all('/<h([1-6])[^>]*>([^<]+)<\/h\1>/i', $html, $matches);
        
        if (empty($matches[0])) {
            $issues[] = 'No headings found in content';
            return $issues;
        }
        
        $h1Count = 0;
        $lastLevel = 0;
        
        foreach ($matches[1] as $index => $level) {
            $level = intval($level);
            $text = $matches[2][$index];
            
            // Check for multiple H1s
            if ($level === 1) {
                $h1Count++;
            }
            
            // Check for skipped heading levels
            if ($index > 0 && $level > $lastLevel + 1) {
                $issues[] = "Skipped heading level from H{$lastLevel} to H{$level} at '{$text}'";
            }
            
            $lastLevel = $level;
        }
        
        if ($h1Count > 1) {
            $issues[] = "Multiple H1 headings found ({$h1Count}). Should be exactly 1 per page.";
        }
        
        if ($h1Count === 0) {
            $issues[] = 'No H1 heading found. Every page should have exactly one H1.';
        }
        
        return $issues;
    }
}

/**
 * Quick heading functions
 */
function h1($text, $class = '', $id = '') {
    return HeadingHelper::h1($text, $class, $id);
}

function h2($text, $class = '', $id = '') {
    return HeadingHelper::h2($text, $class, $id);
}

function h3($text, $class = '', $id = '') {
    return HeadingHelper::h3($text, $class, $id);
}

function heading($level, $text, $class = '', $id = '') {
    return match($level) {
        1 => h1($text, $class, $id),
        2 => h2($text, $class, $id),
        3 => h3($text, $class, $id),
        4 => HeadingHelper::h4($text, $class, $id),
        5 => HeadingHelper::h5($text, $class, $id),
        6 => HeadingHelper::h6($text, $class, $id),
        default => h2($text, $class, $id)
    };
}
?>
