<?php
/**
 * whp-ui.php — small, dependency-free PHP render helpers for the UX/a11y sweep.
 *
 * These exist so the icon-button accessibility pass is CONSISTENT across pages:
 * every icon-only control gets a real accessible name (aria-label + title) and
 * the decorative <i> is hidden from assistive tech (aria-hidden="true"). All
 * user-facing text is escaped with htmlspecialchars(); each helper returns a
 * string (it does not echo).
 *
 * Icons are Font Awesome 4.x (`<i class="fa fa-…">`), matching the WHP theme.
 *
 * Usage:
 *   require_once('/docker/whp/web/includes/whp-ui.php');
 *   echo whp_icon_button('fa-trash', 'Delete database', [
 *       'class' => 'btn-sm btn-danger',
 *       'attrs' => 'data-id="' . (int)$id . '"',   // caller pre-escapes attrs
 *   ]);
 *   echo whp_icon_link('?page=edit&id=5', 'fa-pencil', 'Edit site', [
 *       'class' => 'btn-sm btn-secondary',
 *   ]);
 *
 * opts (both helpers): class, text (visible label after the icon), attrs (a raw,
 *   already-escaped extra-attributes string, e.g. 'data-id="5"').
 * whp_icon_link adds: newTab (bool — target="_blank" rel="noopener noreferrer").
 * whp_icon_button adds: type (button|submit|reset; default 'button').
 *
 * Accessibility contract: an empty $accessibleName is a BUG. Rather than ship a
 * silently-unlabeled control, these render a loud placeholder label
 * ("UNLABELED BUTTON — fix me" / "UNLABELED LINK — fix me") AND raise an
 * E_USER_WARNING so it surfaces in the error log during development.
 */

if (!function_exists('whp_icon_button')) {

    /** Normalize an accessible name; flag empties loudly instead of failing silent. */
    function whp_ui_accessible_name(string $name, string $what): string {
        $name = trim($name);
        if ($name === '') {
            trigger_error("whp-ui: $what rendered without an accessible name", E_USER_WARNING);
            return 'UNLABELED ' . strtoupper($what) . ' — fix me';
        }
        return $name;
    }

    /**
     * Render an icon button with a guaranteed accessible name.
     *
     * @param string $faIcon          Font Awesome 4 class, e.g. 'fa-trash'.
     * @param string $accessibleName  Required. Used for aria-label + title.
     * @param array  $opts            class, type, text, attrs (see file docblock).
     */
    function whp_icon_button(string $faIcon, string $accessibleName, array $opts = []): string {
        $name  = whp_ui_accessible_name($accessibleName, 'button');
        $class = (string) ($opts['class'] ?? 'btn-sm btn-secondary');
        $type  = (string) ($opts['type'] ?? 'button');
        $text  = (string) ($opts['text'] ?? '');
        $attrs = (string) ($opts['attrs'] ?? '');

        $eName  = htmlspecialchars($name, ENT_QUOTES);
        $eClass = htmlspecialchars($class, ENT_QUOTES);
        $eType  = htmlspecialchars($type, ENT_QUOTES);
        $eIcon  = htmlspecialchars($faIcon, ENT_QUOTES);

        $html  = '<button type="' . $eType . '" class="btn ' . $eClass . '"';
        $html .= ' aria-label="' . $eName . '" title="' . $eName . '"';
        if ($attrs !== '') { $html .= ' ' . $attrs; }
        $html .= '><i class="fa ' . $eIcon . '" aria-hidden="true"></i>';
        if ($text !== '') { $html .= ' ' . htmlspecialchars($text, ENT_QUOTES); }
        $html .= '</button>';
        return $html;
    }

    /**
     * Render an icon link with a guaranteed accessible name.
     *
     * @param string $href            Destination URL.
     * @param string $faIcon          Font Awesome 4 class, e.g. 'fa-pencil'.
     * @param string $accessibleName  Required. Used for aria-label + title.
     * @param array  $opts            class, text, attrs, newTab (see file docblock).
     */
    function whp_icon_link(string $href, string $faIcon, string $accessibleName, array $opts = []): string {
        $name  = whp_ui_accessible_name($accessibleName, 'link');
        $class = (string) ($opts['class'] ?? 'btn-sm btn-secondary');
        $text  = (string) ($opts['text'] ?? '');
        $attrs = (string) ($opts['attrs'] ?? '');
        $newTab = !empty($opts['newTab']);

        $eHref  = htmlspecialchars($href, ENT_QUOTES);
        $eName  = htmlspecialchars($name, ENT_QUOTES);
        $eClass = htmlspecialchars($class, ENT_QUOTES);
        $eIcon  = htmlspecialchars($faIcon, ENT_QUOTES);

        $html  = '<a href="' . $eHref . '" class="btn ' . $eClass . '"';
        $html .= ' aria-label="' . $eName . '" title="' . $eName . '"';
        if ($newTab) { $html .= ' target="_blank" rel="noopener noreferrer"'; }
        if ($attrs !== '') { $html .= ' ' . $attrs; }
        $html .= '><i class="fa ' . $eIcon . '" aria-hidden="true"></i>';
        if ($text !== '') { $html .= ' ' . htmlspecialchars($text, ENT_QUOTES); }
        $html .= '</a>';
        return $html;
    }
}
