<?php

declare( strict_types=1 );

namespace AcezSeo\Support;

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

/**
 * Allow-lists for `wp_kses()` covering the markup this plugin builds itself
 * and prints in the admin: inline SVG icons, and the help-icon button that
 * wraps one of them.
 *
 * Why this exists: both were previously printed under a
 * `phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped` with a
 * comment explaining that the markup is static or already escaped. Those
 * comments were accurate, but a suppression is invisible to a scanner — the
 * WP.org reviewer's tooling counts occurrences, not justifications, and
 * flagged them in the second review round (M74). Passing the same markup
 * through `wp_kses()` is a real, machine-checkable escape, so the
 * suppression disappears instead of being explained a second time.
 *
 * The lists are deliberately narrow: exactly the elements and attributes
 * used by the icon builders. Adding a new shape to an icon means adding it
 * here as well — that is the mechanism working, not an inconvenience.
 *
 * Note on `viewBox`: `wp_kses()` lowercases attribute names, so it emits
 * `viewbox`. The HTML parser's "adjust SVG attributes" step maps that back
 * to camel-case for inline SVG, so rendering is unaffected.
 *
 * @return array<string, array<string, bool>>
 */
final class KsesTags
{
	/**
	 * Inline SVG icons.
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function svg(): array
	{
		$shape = array(
			'fill'            => true,
			'stroke'          => true,
			'stroke-width'    => true,
			'stroke-linecap'  => true,
			'stroke-linejoin' => true,
			'class'           => true,
		);

		return array(
			'svg'      => $shape + array(
				'xmlns'       => true,
				'viewbox'     => true,
				'width'       => true,
				'height'      => true,
				'role'        => true,
				'focusable'   => true,
				'aria-hidden' => true,
			),
			'g'        => $shape,
			'title'    => array(),
			'path'     => $shape + array( 'd' => true ),
			'circle'   => $shape + array( 'cx' => true, 'cy' => true, 'r' => true ),
			'ellipse'  => $shape + array( 'cx' => true, 'cy' => true, 'rx' => true, 'ry' => true ),
			'rect'     => $shape + array( 'x' => true, 'y' => true, 'width' => true, 'height' => true, 'rx' => true, 'ry' => true ),
			'line'     => $shape + array( 'x1' => true, 'y1' => true, 'x2' => true, 'y2' => true ),
			'polyline' => $shape + array( 'points' => true ),
			'polygon'  => $shape + array( 'points' => true ),
			'text'     => $shape + array( 'x' => true, 'y' => true, 'dy' => true, 'font-size' => true, 'text-anchor' => true ),
		);
	}

	/**
	 * The help-icon trigger: a button wrapping one of the SVG icons above.
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function help_icon(): array
	{
		return self::svg() + array(
			'button' => array(
				'type'          => true,
				'class'         => true,
				'data-help-key' => true,
				'aria-expanded' => true,
				'aria-haspopup' => true,
				'aria-label'    => true,
			),
		);
	}

	/**
	 * A plain inline link, already built from esc_url()/esc_html__() parts —
	 * running it through wp_kses() at the point of output is what lets the
	 * printf() argument carry no suppression.
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function link(): array
	{
		return array(
			'a' => array(
				'href'   => true,
				'class'  => true,
				'target' => true,
				'rel'    => true,
				'title'  => true,
			),
		);
	}

	/**
	 * The collapsible-card toggle: a button wrapping one of the SVG icons.
	 * Kept separate from help_icon() because the attributes differ
	 * (data-card / aria-controls instead of data-help-key).
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function card_toggle(): array
	{
		return self::svg() + array(
			'button' => array(
				'type'          => true,
				'class'         => true,
				'data-card'     => true,
				'aria-expanded' => true,
				'aria-controls' => true,
				'aria-label'    => true,
			),
		);
	}

	/**
	 * Attachment markup as returned by wp_get_attachment_image(): an <img>
	 * with the responsive attributes core adds (srcset/sizes/loading/decoding).
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function attachment_image(): array
	{
		return array(
			'img' => array(
				'src'      => true,
				'srcset'   => true,
				'sizes'    => true,
				'alt'      => true,
				'width'    => true,
				'height'   => true,
				'class'    => true,
				'id'       => true,
				'style'    => true,
				'loading'  => true,
				'decoding' => true,
				'fetchpriority' => true,
				'title'    => true,
			),
		);
	}

	/**
	 * The "generate with AI" trigger next to a settings field. Kept separate
	 * from help_icon()/card_toggle() for the same reason those are separate
	 * from each other — the attributes differ (data-field / data-target, read
	 * by the shared meta-box-ai.js click handler).
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function ai_button(): array
	{
		return array(
			'button' => array(
				'type'        => true,
				'class'       => true,
				'data-field'  => true,
				'data-target' => true,
			),
			'p'      => array( 'class' => true ),
		);
	}

	/**
	 * An icon plus a short text label (Pro teaser badges).
	 *
	 * @return array<string, array<string, bool>>
	 */
	public static function badge(): array
	{
		return self::svg() + array(
			'span' => array( 'class' => true, 'title' => true ),
			'a'    => array( 'class' => true, 'href' => true, 'target' => true, 'rel' => true, 'title' => true ),
			'em'   => array( 'class' => true ),
			'strong' => array( 'class' => true ),
		);
	}
}