<?php
/**
 * Parses a page's HTML and applies the rule set.
 *
 * @package AdinavAccessibilityAuditEAA
 */

defined( 'ABSPATH' ) || exit;

class ADNVAA_Analyzer {

	/** @var DOMDocument */
	private $doc;

	/** @var DOMXPath */
	private $xp;

	/** @var array */
	private $issues = array();

	/**
	 * @param string $html Raw HTML of a rendered page.
	 * @return array|WP_Error List of issues.
	 */
	public function analyze( $html ) {
		if ( ! class_exists( 'DOMDocument' ) ) {
			return new WP_Error( 'adnvaa_no_dom', __( 'The PHP DOM extension is not available on this server, so the page cannot be parsed.', 'adinav-accessibility-audit-eaa' ) );
		}

		$this->issues = array();

		$prev = libxml_use_internal_errors( true );
		$this->doc = new DOMDocument();
		// Force UTF-8. Without this, libxml assumes ISO-8859-1 and mangles accented
		// characters — which on a French site means most of the page.
		$loaded = $this->doc->loadHTML(
			'<?xml encoding="UTF-8">' . $html,
			LIBXML_NOWARNING | LIBXML_NOERROR | LIBXML_NONET
		);
		libxml_clear_errors();
		libxml_use_internal_errors( $prev );

		if ( ! $loaded ) {
			return new WP_Error( 'adnvaa_parse_failed', __( 'The page HTML could not be parsed.', 'adinav-accessibility-audit-eaa' ) );
		}

		$this->xp = new DOMXPath( $this->doc );

		$this->check_images();
		$this->check_form_labels();
		$this->check_control_names();
		$this->check_generic_links();
		$this->check_document();
		$this->check_headings();
		$this->check_iframes();
		$this->check_tables();
		$this->check_duplicate_ids();
		$this->check_tabindex();
		$this->check_aria_hidden_focusable();
		$this->check_viewport();
		$this->check_meta_refresh();
		$this->check_media();
		$this->check_autocomplete();
		$this->check_landmarks();
		$this->check_inline_contrast();

		usort(
			$this->issues,
			static function ( $a, $b ) {
				$sa = ADNVAA_Rules::severity_rank( $a['severity'] );
				$sb = ADNVAA_Rules::severity_rank( $b['severity'] );
				return $sa === $sb ? strcmp( $a['rule'], $b['rule'] ) : $sa - $sb;
			}
		);

		return $this->issues;
	}

	// ---------------------------------------------------------------- rules --

	private function check_images() {
		foreach ( $this->xp->query( '//img' ) as $img ) {
			if ( $this->is_hidden_from_at( $img ) ) {
				continue;
			}

			if ( ! $img->hasAttribute( 'alt' ) ) {
				// An <img> inside a link/button that already has a name elsewhere is
				// still a fault, but it is the control-name rule's job to shout about
				// the blocking case. Here we report the missing attribute plainly.
				$this->add( 'img-missing-alt', $img );
				continue;
			}

			$alt = trim( $img->getAttribute( 'alt' ) );
			if ( '' === $alt ) {
				continue; // Explicitly decorative. Correct and intentional.
			}

			if ( preg_match( '/\.(jpe?g|png|gif|webp|svg|avif|bmp)$/i', $alt ) ) {
				$this->add( 'img-alt-is-filename', $img, sprintf( 'alt="%s"', $alt ) );
				continue;
			}

			// alt that merely repeats the file name without the extension.
			$src = $img->getAttribute( 'src' );
			if ( $src ) {
				$base = pathinfo( wp_parse_url( $src, PHP_URL_PATH ) ?: '', PATHINFO_FILENAME );
				if ( $base && 0 === strcasecmp( $base, $alt ) ) {
					$this->add( 'img-alt-is-filename', $img, sprintf( 'alt="%s"', $alt ) );
				}
			}
		}
	}

	private function check_form_labels() {
		$controls = $this->xp->query(
			'//input[not(@type) or (translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz") != "hidden"'
			. ' and translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz") != "submit"'
			. ' and translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz") != "button"'
			. ' and translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz") != "reset"'
			. ' and translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz") != "image")]'
			. ' | //select | //textarea'
		);

		foreach ( $controls as $ctrl ) {
			if ( $this->is_hidden_from_at( $ctrl ) ) {
				continue;
			}
			if ( '' !== $this->accessible_name( $ctrl ) ) {
				continue;
			}
			// A placeholder is deliberately NOT accepted as a name: it vanishes on
			// input and several screen readers never announce it. WCAG agrees.
			$this->add( 'input-missing-label', $ctrl );
		}
	}

	private function check_control_names() {
		// Links that are actual links (have href) and buttons.
		$controls = $this->xp->query( '//a[@href] | //button | //input[translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="image"]' );

		foreach ( $controls as $ctrl ) {
			if ( $this->is_hidden_from_at( $ctrl ) ) {
				continue;
			}
			if ( '' === $this->accessible_name( $ctrl ) ) {
				$this->add( 'control-no-accessible-name', $ctrl );
			}
		}
	}

	private function check_generic_links() {
		foreach ( $this->xp->query( '//a[@href]' ) as $a ) {
			if ( $this->is_hidden_from_at( $a ) ) {
				continue;
			}
			$name = $this->accessible_name( $a );
			if ( '' === $name ) {
				continue; // Already reported as nameless; do not double-count.
			}
			$norm = trim( mb_strtolower( $name ), " \t\n\r\0\x0B.:;!?→>»…" );
			if ( in_array( $norm, ADNVAA_Rules::GENERIC_LINK_TEXT, true ) ) {
				$this->add( 'link-generic-text', $a, sprintf( '"%s"', $name ) );
			}
		}
	}

	private function check_document() {
		$html = $this->xp->query( '//html' )->item( 0 );
		if ( $html && '' === trim( (string) $html->getAttribute( 'lang' ) ) ) {
			$this->add( 'html-missing-lang', $html );
		}

		$title = $this->xp->query( '//head/title' )->item( 0 );
		if ( ! $title || '' === trim( $title->textContent ) ) {
			$this->add( 'missing-page-title', $title ?: $html );
		}
	}

	private function check_headings() {
		$headings = $this->xp->query( '//h1|//h2|//h3|//h4|//h5|//h6' );

		$last  = 0;
		$h1    = 0;
		$seen  = false;

		foreach ( $headings as $h ) {
			if ( $this->is_hidden_from_at( $h ) ) {
				continue;
			}
			$level = (int) substr( $h->nodeName, 1 );

			if ( '' === trim( $this->accessible_name( $h ) ) ) {
				$this->add( 'empty-heading', $h );
				continue;
			}

			if ( 1 === $level ) {
				$h1++;
			}

			if ( $seen && $level > $last + 1 ) {
				$this->add(
					'heading-level-skipped',
					$h,
					sprintf(
						/* translators: 1: previous heading level, 2: this heading level */
						__( 'h%1$d is followed by h%2$d', 'adinav-accessibility-audit-eaa' ),
						$last,
						$level
					)
				);
			}

			$last = $level;
			$seen = true;
		}

		if ( 0 === $h1 && $headings->length > 0 ) {
			$this->add( 'no-h1', $this->xp->query( '//body' )->item( 0 ) );
		}
	}

	private function check_iframes() {
		foreach ( $this->xp->query( '//iframe' ) as $f ) {
			if ( $this->is_hidden_from_at( $f ) ) {
				continue;
			}
			$name = trim( $f->getAttribute( 'title' ) ) . trim( $f->getAttribute( 'aria-label' ) );
			if ( '' === $name && '' === trim( $f->getAttribute( 'aria-labelledby' ) ) ) {
				$this->add( 'iframe-no-title', $f );
			}
		}
	}

	private function check_tables() {
		foreach ( $this->xp->query( '//table' ) as $t ) {
			$role = strtolower( $t->getAttribute( 'role' ) );
			if ( 'presentation' === $role || 'none' === $role ) {
				continue; // Declared as layout. Honour the declaration.
			}
			if ( $this->is_hidden_from_at( $t ) ) {
				continue;
			}
			// A table with no rows is not a data table worth complaining about.
			if ( 0 === $this->xp->query( './/tr', $t )->length ) {
				continue;
			}
			if ( 0 === $this->xp->query( './/th', $t )->length ) {
				$this->add( 'table-no-headers', $t );
			}
		}
	}

	private function check_duplicate_ids() {
		$seen = array();
		foreach ( $this->xp->query( '//*[@id]' ) as $el ) {
			$id = $el->getAttribute( 'id' );
			if ( '' === trim( $id ) ) {
				continue;
			}
			if ( isset( $seen[ $id ] ) ) {
				$this->add( 'duplicate-id', $el, sprintf( 'id="%s"', $id ) );
			}
			$seen[ $id ] = true;
		}
	}

	private function check_tabindex() {
		foreach ( $this->xp->query( '//*[@tabindex]' ) as $el ) {
			if ( (int) $el->getAttribute( 'tabindex' ) > 0 ) {
				$this->add( 'positive-tabindex', $el, sprintf( 'tabindex="%s"', $el->getAttribute( 'tabindex' ) ) );
			}
		}
	}

	/**
	 * Reported once per aria-hidden CONTAINER, not once per trapped element.
	 *
	 * A single aria-hidden mobile menu can contain a thousand links. Emitting a
	 * thousand rows is technically accurate and completely useless: it buries the
	 * twenty-three broken "add to cart" buttons that actually cost the business
	 * money. There is one bug here — one wrong attribute on one wrapper — the
	 * developer fixes it in one place, so we report it in one place and say how
	 * many controls it swallows.
	 */
	private function check_aria_hidden_focusable() {
		$focusable = './/a[@href] | .//button | .//input[not(@type) or translate(@type,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")!="hidden"] | .//select | .//textarea | .//*[@tabindex]';

		foreach ( $this->xp->query( '//*[@aria-hidden="true"]' ) as $el ) {
			// Skip nested aria-hidden containers: the outermost one is what gets fixed.
			$ancestor_hidden = false;
			$p               = $el->parentNode;
			while ( $p instanceof DOMElement ) {
				if ( 'true' === strtolower( $p->getAttribute( 'aria-hidden' ) ) ) {
					$ancestor_hidden = true;
					break;
				}
				$p = $p->parentNode;
			}
			if ( $ancestor_hidden ) {
				continue;
			}

			$trapped = 0;
			foreach ( $this->xp->query( $focusable, $el ) as $inner ) {
				// tabindex="-1" removes it from the tab order, resolving the conflict.
				if ( $inner->hasAttribute( 'tabindex' ) && (int) $inner->getAttribute( 'tabindex' ) < 0 ) {
					continue;
				}
				if ( $inner->hasAttribute( 'disabled' ) ) {
					continue;
				}
				$trapped++;
			}

			if ( $trapped > 0 ) {
				$this->add(
					'aria-hidden-focusable',
					$el,
					sprintf(
						/* translators: %d: number of keyboard-focusable controls inside the hidden container */
						_n(
							'This aria-hidden="true" container still holds %d keyboard-focusable control.',
							'This aria-hidden="true" container still holds %d keyboard-focusable controls.',
							$trapped,
							'adinav-accessibility-audit-eaa'
						),
						$trapped
					)
				);
			}
		}
	}

	private function check_viewport() {
		foreach ( $this->xp->query( '//meta[translate(@name,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="viewport"]' ) as $m ) {
			$content = strtolower( str_replace( ' ', '', $m->getAttribute( 'content' ) ) );

			if ( false !== strpos( $content, 'user-scalable=no' ) || false !== strpos( $content, 'user-scalable=0' ) ) {
				$this->add( 'viewport-zoom-disabled', $m, 'user-scalable=no' );
				continue;
			}
			if ( preg_match( '/maximum-scale=([0-9.]+)/', $content, $m2 ) && (float) $m2[1] < 2 ) {
				$this->add( 'viewport-zoom-disabled', $m, 'maximum-scale=' . $m2[1] );
			}
		}
	}

	private function check_meta_refresh() {
		foreach ( $this->xp->query( '//meta[translate(@http-equiv,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="refresh"]' ) as $m ) {
			$content = trim( $m->getAttribute( 'content' ) );
			// content="0; url=…" is an immediate redirect — annoying but not a WCAG
			// timing failure, because nothing is on screen long enough to be lost.
			if ( preg_match( '/^\s*([0-9.]+)/', $content, $sec ) && (float) $sec[1] > 0 ) {
				$this->add( 'meta-refresh', $m, sprintf( 'content="%s"', $content ) );
			}
		}
	}

	private function check_media() {
		foreach ( $this->xp->query( '//video' ) as $v ) {
			if ( 0 === $this->xp->query( './/track[translate(@kind,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="captions" or translate(@kind,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="subtitles"]', $v )->length ) {
				$this->add( 'video-no-captions', $v );
			}
		}

		foreach ( $this->xp->query( '//video[@autoplay] | //audio[@autoplay]' ) as $m ) {
			if ( $m->hasAttribute( 'muted' ) ) {
				continue; // Silent autoplay does not talk over a screen reader.
			}
			$this->add( 'media-autoplays', $m );
		}
	}

	/**
	 * WCAG 1.3.5 (AA). Only fires where the field's purpose is unambiguous from
	 * its type or its name/id, so we never guess at what a field is for.
	 */
	private function check_autocomplete() {
		$tokens = array(
			'email'      => array( 'email', 'e-mail', 'mail', 'courriel' ),
			'tel'        => array( 'tel', 'phone', 'telephone', 'mobile' ),
			'given-name' => array( 'firstname', 'first-name', 'first_name', 'fname', 'prenom' ),
			'family-name'=> array( 'lastname', 'last-name', 'last_name', 'lname', 'surname', 'nom' ),
			'postal-code'=> array( 'zip', 'zipcode', 'postcode', 'postal', 'cp' ),
			'street-address' => array( 'address', 'street', 'adresse', 'rue' ),
		);

		foreach ( $this->xp->query( '//input' ) as $in ) {
			$type = strtolower( $in->getAttribute( 'type' ) );
			if ( in_array( $type, array( 'hidden', 'submit', 'button', 'reset', 'image', 'checkbox', 'radio', 'file' ), true ) ) {
				continue;
			}
			if ( '' !== trim( $in->getAttribute( 'autocomplete' ) ) ) {
				continue;
			}
			if ( $this->is_hidden_from_at( $in ) ) {
				continue;
			}

			$expected = '';
			if ( 'email' === $type ) {
				$expected = 'email';
			} elseif ( 'tel' === $type ) {
				$expected = 'tel';
			} else {
				$needle = strtolower( $in->getAttribute( 'name' ) . ' ' . $in->getAttribute( 'id' ) );
				if ( '' === trim( $needle ) ) {
					continue;
				}
				foreach ( $tokens as $token => $hints ) {
					foreach ( $hints as $hint ) {
						if ( false !== strpos( $needle, $hint ) ) {
							$expected = $token;
							break 2;
						}
					}
				}
			}

			if ( '' === $expected ) {
				continue; // Purpose not determinable from the markup. Stay silent.
			}

			$this->add(
				'autocomplete-missing',
				$in,
				sprintf(
					/* translators: %s: the autocomplete token that should be used */
					__( 'expected autocomplete="%s"', 'adinav-accessibility-audit-eaa' ),
					$expected
				)
			);
		}
	}

	private function check_landmarks() {
		$main = $this->xp->query( '//main | //*[translate(@role,"ABCDEFGHIJKLMNOPQRSTUVWXYZ","abcdefghijklmnopqrstuvwxyz")="main"]' );
		if ( 0 === $main->length ) {
			$this->add( 'no-main-landmark', $this->xp->query( '//body' )->item( 0 ) );
		}
	}

	/**
	 * Only judges contrast where BOTH colours are declared on the same inline style.
	 * That is a small share of a real page — and it is the share we can be certain
	 * about without a rendering engine. The report says so out loud rather than
	 * letting a clean result imply a pass.
	 */
	private function check_inline_contrast() {
		foreach ( $this->xp->query( '//*[@style]' ) as $el ) {
			$style = strtolower( $el->getAttribute( 'style' ) );

			if ( ! preg_match( '/(?:^|;)\s*color\s*:\s*([^;]+)/', $style, $fg ) ) {
				continue;
			}
			if ( ! preg_match( '/background(?:-color)?\s*:\s*([^;]+)/', $style, $bg ) ) {
				continue;
			}

			$c1 = self::parse_color( $fg[1] );
			$c2 = self::parse_color( $bg[1] );
			if ( ! $c1 || ! $c2 ) {
				continue;
			}

			$ratio = self::contrast_ratio( $c1, $c2 );

			// 3:1 is permitted for large text. We cannot always know the rendered size,
			// so we only assert failure below 3:1 unless the inline style proves the
			// text is small. Erring toward silence, on purpose.
			$threshold = 3.0;
			if ( preg_match( '/font-size\s*:\s*([0-9.]+)px/', $style, $fs ) ) {
				$px   = (float) $fs[1];
				$bold = (bool) preg_match( '/font-weight\s*:\s*(bold|[7-9]00)/', $style );
				$large = $px >= 24 || ( $bold && $px >= 18.66 );
				$threshold = $large ? 3.0 : 4.5;
			}

			if ( $ratio < $threshold ) {
				$this->add(
					'contrast-inline-fail',
					$el,
					sprintf(
						/* translators: 1: measured contrast ratio, 2: required ratio */
						__( 'measured %1$s:1, requires %2$s:1', 'adinav-accessibility-audit-eaa' ),
						number_format( $ratio, 2 ),
						number_format( $threshold, 1 )
					)
				);
			}
		}
	}

	// ------------------------------------------------------------- helpers --

	/**
	 * A deliberately conservative accessible-name computation. It follows the
	 * priority order of the ACCNAME spec closely enough for static analysis:
	 * aria-labelledby → aria-label → native label / content → title.
	 */
	private function accessible_name( DOMElement $el ) {
		// 1. aria-labelledby
		$ref = trim( $el->getAttribute( 'aria-labelledby' ) );
		if ( '' !== $ref ) {
			$text = '';
			foreach ( preg_split( '/\s+/', $ref ) as $id ) {
				$target = $this->element_by_id( $id );
				if ( $target ) {
					$text .= ' ' . $target->textContent;
				}
			}
			if ( '' !== trim( $text ) ) {
				return $this->squash( $text );
			}
		}

		// 2. aria-label
		$label = trim( $el->getAttribute( 'aria-label' ) );
		if ( '' !== $label ) {
			return $this->squash( $label );
		}

		$tag = strtolower( $el->nodeName );

		// 3. Native labelling for form controls.
		if ( in_array( $tag, array( 'input', 'select', 'textarea' ), true ) ) {
			$id = trim( $el->getAttribute( 'id' ) );
			if ( '' !== $id ) {
				$escaped = str_replace( '"', '', $id );
				$for = $this->xp->query( sprintf( '//label[@for="%s"]', $escaped ) );
				if ( $for->length && '' !== trim( $for->item( 0 )->textContent ) ) {
					return $this->squash( $for->item( 0 )->textContent );
				}
			}
			// Wrapping <label>.
			$anc = $el->parentNode;
			while ( $anc instanceof DOMElement ) {
				if ( 'label' === strtolower( $anc->nodeName ) ) {
					$text = $this->squash( $anc->textContent );
					if ( '' !== $text ) {
						return $text;
					}
				}
				$anc = $anc->parentNode;
			}
			// <input type="image"> takes its name from alt.
			if ( 'input' === $tag && 'image' === strtolower( $el->getAttribute( 'type' ) ) ) {
				$alt = trim( $el->getAttribute( 'alt' ) );
				if ( '' !== $alt ) {
					return $this->squash( $alt );
				}
			}
			$value = trim( $el->getAttribute( 'value' ) );
			if ( '' !== $value && in_array( strtolower( $el->getAttribute( 'type' ) ), array( 'submit', 'button', 'reset' ), true ) ) {
				return $this->squash( $value );
			}
		} else {
			// 4. Content: text, plus alt text of images, plus <title> inside an SVG.
			$text = $this->squash( $el->textContent );
			if ( '' !== $text ) {
				return $text;
			}
			foreach ( $this->xp->query( './/img[@alt]', $el ) as $img ) {
				$alt = $this->squash( $img->getAttribute( 'alt' ) );
				if ( '' !== $alt ) {
					return $alt;
				}
			}
			foreach ( $this->xp->query( './/svg', $el ) as $svg ) {
				$svg_label = $this->squash( $svg->getAttribute( 'aria-label' ) );
				if ( '' !== $svg_label ) {
					return $svg_label;
				}
				$svg_title = $this->xp->query( './/*[local-name()="title"]', $svg );
				if ( $svg_title->length && '' !== $this->squash( $svg_title->item( 0 )->textContent ) ) {
					return $this->squash( $svg_title->item( 0 )->textContent );
				}
			}
		}

		// 5. title attribute — a last resort, and a poor one, but it is a name.
		$title = trim( $el->getAttribute( 'title' ) );
		if ( '' !== $title ) {
			return $this->squash( $title );
		}

		return '';
	}

	private function element_by_id( $id ) {
		$escaped = str_replace( '"', '', $id );
		$found   = $this->xp->query( sprintf( '//*[@id="%s"]', $escaped ) );
		return $found->length ? $found->item( 0 ) : null;
	}

	/**
	 * True if the element is hidden from everyone, including assistive technology.
	 * We must not report issues on things nobody can reach — that is the noise
	 * that gets accessibility tools uninstalled.
	 */
	private function is_hidden_from_at( DOMNode $node ) {
		$el = $node;
		while ( $el instanceof DOMElement ) {
			if ( 'true' === strtolower( $el->getAttribute( 'aria-hidden' ) ) ) {
				return true;
			}
			if ( $el->hasAttribute( 'hidden' ) ) {
				return true;
			}
			$style = strtolower( str_replace( ' ', '', $el->getAttribute( 'style' ) ) );
			if ( false !== strpos( $style, 'display:none' ) || false !== strpos( $style, 'visibility:hidden' ) ) {
				return true;
			}
			if ( 'template' === strtolower( $el->nodeName ) || 'script' === strtolower( $el->nodeName ) || 'noscript' === strtolower( $el->nodeName ) ) {
				return true;
			}
			$el = $el->parentNode;
		}
		return false;
	}

	private function squash( $text ) {
		return trim( preg_replace( '/\s+/u', ' ', (string) $text ) );
	}

	private function add( $rule_id, $node, $detail = '' ) {
		$rule = ADNVAA_Rules::get( $rule_id );
		if ( ! $rule ) {
			return;
		}
		$this->issues[] = array(
			'rule'     => $rule_id,
			'severity' => $rule['severity'],
			'selector' => $node instanceof DOMNode ? $this->dom_path( $node ) : '',
			'snippet'  => $node instanceof DOMNode ? $this->snippet( $node ) : '',
			'detail'   => $detail,
		);
	}

	/**
	 * A CSS-ish path that a developer can actually paste into the browser console.
	 */
	private function dom_path( DOMNode $node ) {
		$parts = array();
		$el    = $node;

		while ( $el instanceof DOMElement && 'html' !== strtolower( $el->nodeName ) ) {
			$name = strtolower( $el->nodeName );

			$id = trim( $el->getAttribute( 'id' ) );
			if ( '' !== $id && ! preg_match( '/\d{4,}/', $id ) ) {
				array_unshift( $parts, $name . '#' . $id );
				break; // An id is unique; no need to walk further up.
			}

			$index = 1;
			$sib   = $el->previousSibling;
			while ( $sib ) {
				if ( $sib instanceof DOMElement && strtolower( $sib->nodeName ) === $name ) {
					$index++;
				}
				$sib = $sib->previousSibling;
			}
			array_unshift( $parts, 1 === $index ? $name : sprintf( '%s:nth-of-type(%d)', $name, $index ) );

			$el = $el->parentNode;
		}

		return implode( ' > ', $parts );
	}

	private function snippet( DOMNode $node, $max = 220 ) {
		$html = $this->doc->saveHTML( $node );
		$html = preg_replace( '/\s+/u', ' ', (string) $html );
		$html = trim( $html );
		if ( mb_strlen( $html ) > $max ) {
			$html = mb_substr( $html, 0, $max ) . '…';
		}
		return $html;
	}

	// ------------------------------------------------------- colour helpers --

	/**
	 * @return array|null [r, g, b] 0-255, or null if the value is not a colour we
	 *                    can resolve with certainty (var(), currentColor, gradients…).
	 */
	public static function parse_color( $value ) {
		$value = trim( strtolower( $value ) );
		$value = preg_replace( '/\s*!important\s*$/', '', $value );

		$named = array(
			'black' => array( 0, 0, 0 ),
			'white' => array( 255, 255, 255 ),
			'red'   => array( 255, 0, 0 ),
			'green' => array( 0, 128, 0 ),
			'blue'  => array( 0, 0, 255 ),
			'gray'  => array( 128, 128, 128 ),
			'grey'  => array( 128, 128, 128 ),
			'silver'=> array( 192, 192, 192 ),
			'navy'  => array( 0, 0, 128 ),
			'teal'  => array( 0, 128, 128 ),
			'olive' => array( 128, 128, 0 ),
			'maroon'=> array( 128, 0, 0 ),
			'purple'=> array( 128, 0, 128 ),
			'yellow'=> array( 255, 255, 0 ),
			'orange'=> array( 255, 165, 0 ),
			'lime'  => array( 0, 255, 0 ),
			'aqua'  => array( 0, 255, 255 ),
			'fuchsia' => array( 255, 0, 255 ),
		);
		if ( isset( $named[ $value ] ) ) {
			return $named[ $value ];
		}

		if ( preg_match( '/^#([0-9a-f]{3})$/', $value, $m ) ) {
			$h = $m[1];
			return array(
				hexdec( $h[0] . $h[0] ),
				hexdec( $h[1] . $h[1] ),
				hexdec( $h[2] . $h[2] ),
			);
		}
		if ( preg_match( '/^#([0-9a-f]{6})$/', $value, $m ) ) {
			return array(
				hexdec( substr( $m[1], 0, 2 ) ),
				hexdec( substr( $m[1], 2, 2 ) ),
				hexdec( substr( $m[1], 4, 2 ) ),
			);
		}
		if ( preg_match( '/^rgba?\(\s*([0-9]{1,3})\s*[, ]\s*([0-9]{1,3})\s*[, ]\s*([0-9]{1,3})\s*(?:[,\/]\s*([0-9.]+%?)\s*)?\)$/', $value, $m ) ) {
			// A translucent colour composites against something we cannot see from
			// here. Refuse to judge rather than assume white behind it.
			if ( isset( $m[4] ) && '' !== $m[4] ) {
				$alpha = (float) rtrim( $m[4], '%' );
				if ( false !== strpos( $m[4], '%' ) ) {
					$alpha /= 100;
				}
				if ( $alpha < 0.999 ) {
					return null;
				}
			}
			return array( (int) $m[1], (int) $m[2], (int) $m[3] );
		}

		return null; // var(--x), currentColor, transparent, gradients: unknowable here.
	}

	/** WCAG 2.x relative luminance. */
	public static function luminance( array $rgb ) {
		$c = array();
		foreach ( $rgb as $v ) {
			$v = $v / 255;
			$c[] = ( $v <= 0.03928 ) ? $v / 12.92 : pow( ( $v + 0.055 ) / 1.055, 2.4 );
		}
		return 0.2126 * $c[0] + 0.7152 * $c[1] + 0.0722 * $c[2];
	}

	public static function contrast_ratio( array $a, array $b ) {
		$la = self::luminance( $a );
		$lb = self::luminance( $b );
		$hi = max( $la, $lb );
		$lo = min( $la, $lb );
		return ( $hi + 0.05 ) / ( $lo + 0.05 );
	}
}