<?php
/**
 * The kit's builders (0.22.0, docs/UI-PLAN.md §2.3): one PHP function per piece, each returning escaped HTML in the
 * chrome's recipes, so every product's screen is built from the same markup and looks the same. The pieces:
 * buttons, badges and chips, notices, tabs, field rows and controls (input, select, textarea, checks, switch,
 * combobox), dialogs, toasts, empty states, pagers, the table skin, progress and meter, steps, stars, stat tiles and
 * charts (inline SVG, no script). Function wrappers for products live in helpers.php (`rooster_admin_*`).
 *
 * Escape late: every builder escapes what it inserts and the page echoes through Markup::out(). No inline style:
 * a colour is a class of the recipes (a tone) or a custom property printed by Colour::css(). No raw utility class:
 * the recipe is the contract (CONTRACT §8a).
 *
 * @package RoosterAdmin
 */

namespace Rooster\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Static.
 */
final class Ui {

	/**
	 * The tones a badge, a notice, a stat or a chart series may wear.
	 */
	public const TONES = array( 'primary', 'success', 'warning', 'destructive', 'info', 'mono' );

	/**
	 * The button variants.
	 */
	public const BUTTON_VARIANTS = array( 'outline', 'primary', 'secondary', 'ghost', 'destructive', 'mono' );

	/**
	 * A tone, or the fallback.
	 *
	 * @param string $tone     Tone.
	 * @param string $fallback Fallback.
	 */
	private static function tone( string $tone, string $fallback = 'mono' ): string {
		return in_array( $tone, self::TONES, true ) ? $tone : $fallback;
	}

	/**
	 * Attributes as a string (` name="value"`; '' prints the attribute bare), escaped; `href` and `src` as URLs.
	 *
	 * @param array<string, mixed> $attrs name => value.
	 */
	public static function attrs( array $attrs ): string {
		$out = '';
		foreach ( $attrs as $name => $value ) {
			if ( null === $value || false === $value ) {
				continue;
			}
			$name = (string) $name;
			if ( 1 !== preg_match( '/^[a-zA-Z][a-zA-Z0-9:_-]*$/', $name ) ) {
				continue;
			}
			if ( true === $value || '' === $value ) {
				$out .= ' ' . $name;
				continue;
			}
			$out .= ' ' . $name . '="' . ( in_array( $name, array( 'href', 'src', 'formaction' ), true ) ? esc_url( (string) $value ) : esc_attr( (string) $value ) ) . '"';
		}
		return $out;
	}

	/**
	 * A builder's own attributes and a caller's `attrs` (0.84.6, the Rooster One cleanup: a script's hook passed as a
	 * class in a select's `attrs` was dropped, and the navigator's colours never saved): the caller's add to the
	 * builder's, the builder's win where both set one, and the caller's `class` is appended to the builder's own, never
	 * dropped or printed twice.
	 *
	 * @param array<string, mixed> $own  The builder's attributes.
	 * @param mixed                $more The caller's `attrs` (anything but an array is none).
	 * @return array<string, mixed>
	 */
	public static function merge_attrs( array $own, $more ): array {
		$more = is_array( $more ) ? $more : array();
		$add  = trim( (string) ( $more['class'] ?? '' ) );
		unset( $more['class'] );
		if ( '' !== $add ) {
			$own['class'] = trim( (string) ( $own['class'] ?? '' ) . ' ' . $add );
		}
		return $own + $more;
	}

	/**
	 * A caller's `attrs` for a builder that prints its own class first (0.84.6, as merge_attrs()): the classes to append
	 * to it (escaped, with their space), and the rest.
	 *
	 * @param mixed $attrs The caller's `attrs`.
	 * @return array{0: string, 1: array<string, mixed>}
	 */
	private static function split_class( $attrs ): array {
		$attrs = is_array( $attrs ) ? $attrs : array();
		$class = trim( (string) ( $attrs['class'] ?? '' ) );
		unset( $attrs['class'] );
		return array( '' !== $class ? ' ' . esc_attr( $class ) : '', $attrs );
	}

	/**
	 * A button, or a link that looks like one.
	 *
	 * @param string               $label The label (raw).
	 * @param array<string, mixed> $opts  variant (outline, primary, secondary, ghost, destructive, mono), size (sm,
	 *                                    lg), block (fills its row), icon (Lucide name), icon_only (the label
	 *                                    becomes the name and the tip), href (an `<a>`), external (a new tab), type
	 *                                    (button, submit; 0.85.2 reset: a form's Discard), disabled, attrs (more attributes, data-* included), class;
	 *                                    0.59.0: reason (raw: why it is disabled, UI-Final-Review FR7; the button is
	 *                                    disabled and the reason follows it as visible text, tied by aria-describedby,
	 *                                    kept in Compact; its id is the button's `id` attribute with `-reason`, else a
	 *                                    unique one); 0.77.1: done (its action is done for this record: `is-done`, the
	 *                                    success colours and the check in place of its icon; still a button, so the
	 *                                    action runs again; a script marks one done with the class alone).
	 */
	public static function button( string $label, array $opts = array() ): string {
		$reason = (string) ( $opts['reason'] ?? '' );
		if ( '' !== $reason ) {
			$attrs = is_array( $opts['attrs'] ?? null ) ? $opts['attrs'] : array();
			$rid   = ( '' !== (string) ( $attrs['id'] ?? '' ) ? (string) $attrs['id'] : wp_unique_id( 'rooster-admin-button-' ) ) . '-reason';
			$opts  = array(
				'disabled' => true,
				'reason'   => '',
				'attrs'    => array( 'aria-describedby' => trim( (string) ( $attrs['aria-describedby'] ?? '' ) . ' ' . $rid ) ) + $attrs,
			) + $opts;
			return self::button( $label, $opts ) . '<span class="rooster-admin-reason is-essential" id="' . esc_attr( $rid ) . '">' . esc_html( $reason ) . '</span>';
		}
		$variant = (string) ( $opts['variant'] ?? 'outline' );
		$class   = 'rooster-admin-button' . ( in_array( $variant, self::BUTTON_VARIANTS, true ) && 'outline' !== $variant ? ' rooster-admin-button--' . $variant : '' )
			. ( in_array( $opts['size'] ?? '', array( 'sm', 'lg' ), true ) ? ' rooster-admin-button--' . $opts['size'] : '' )
			. ( ! empty( $opts['block'] ) ? ' rooster-admin-button--block' : '' )
			. ( ! empty( $opts['icon_only'] ) ? ' rooster-admin-button--icon' : '' )
			. ( ! empty( $opts['done'] ) ? ' is-done' : '' )
			. ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' );
		$icon    ='' !== (string) ( $opts['icon'] ?? '' ) ? Icons::svg( (string) $opts['icon'], ! empty( $opts['icon_only'] ) ? 16 : 15 ) : '';
		$text    = ! empty( $opts['icon_only'] ) ? '<span class="screen-reader-text">' . esc_html( $label ) . '</span>' : esc_html( $label );
		$attrs   = is_array( $opts['attrs'] ?? null ) ? $opts['attrs'] : array();
		$attrs   = self::merge_attrs( array( 'class' => $class ), $attrs );
		// A link to a new tab says so (0.64.3, WCAG 3.2.5): the icon shows it, the words tell a screen reader.
		$external = ! empty( $opts['external'] ) && '' !== (string) ( $opts['href'] ?? '' );
		$new_tab  = __( '(opens in a new tab)', 'ai-eshop-optimizer' );
		if ( ! empty( $opts['icon_only'] ) ) {
			$attrs += array(
				'aria-label'  => $external ? $label . ' ' . $new_tab : $label,
				'data-ra-tip' => $label,
			);
		}
		if ( '' !== (string) ( $opts['href'] ?? '' ) ) {
			$attrs += array( 'href' => (string) $opts['href'] );
			if ( $external ) {
				$attrs += array(
					'target' => '_blank',
					'rel'    => 'noopener noreferrer',
				);
			}
			if ( ! empty( $opts['disabled'] ) ) {
				$attrs += array( 'aria-disabled' => 'true' );
			}
			return '<a' . self::attrs( $attrs ) . '>' . $icon . $text . ( $external ? Icons::ui( 'external', 13 ) . ( empty( $opts['icon_only'] ) ? '<span class="screen-reader-text"> ' . esc_html( $new_tab ) . '</span>' : '' ) : '' ) . '</a>';
		}
		$attrs += array( 'type' => in_array( $opts['type'] ?? '', array( 'submit', 'reset' ), true ) ? (string) $opts['type'] : 'button' );
		if ( ! empty( $opts['disabled'] ) ) {
			$attrs += array( 'disabled' => true );
		}
		return '<button' . self::attrs( $attrs ) . '>' . $icon . $text . '</button>';
	}

	/**
	 * A badge (a tone on a word), or a chip (an outlined one, removable).
	 *
	 * @param string               $label The word (raw).
	 * @param string               $tone  A tone (TONES).
	 * @param array<string, mixed> $opts  solid (filled), sm, lg (as tall as a small button), dot (a leading dot), chip (outlined, with a remove
	 *                                    button when `remove` is set to a label), icon (Lucide), href (the text
	 *                                    is a link; `href_label` its accessible name), clip (characters), attrs.
	 *                                    0.44.2: html (escaped inline HTML in place of the text: links in a chip;
	 *                                    the label stays what `clip` measures), tip (the clipped chip's tip, by
	 *                                    default the label), class (more classes: a page's state), link_attrs,
	 *                                    remove_attrs (a script's hooks), after (escaped HTML after the text: an
	 *                                    icon link, `rooster-admin-chip__action`).
	 */
	public static function badge( string $label, string $tone = 'mono', array $opts = array() ): string {
		$clip  = (int) ( $opts['clip'] ?? 0 ); // a chip in a tight spot: clipped past this many characters, the full text as its tip (hover and keyboard)
		$long  = $clip > 0 && mb_strlen( $label ) > $clip;
		$class = ( ! empty( $opts['chip'] ) ? 'rooster-admin-chip' : 'rooster-admin-badge' ) . ' is-' . self::tone( $tone )
			. ( ! empty( $opts['solid'] ) ? ' is-solid' : '' ) . ( ! empty( $opts['sm'] ) ? ' is-sm' : '' ) . ( ! empty( $opts['lg'] ) ? ' is-lg' : '' ) . ( $long ? ' is-clipped' : '' )
			. ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' );
		$attrs = self::merge_attrs( array( 'class' => $class ), $opts['attrs'] ?? null );
		if ( $long ) {
			$attrs += array(
				'data-ra-tip' => (string) ( $opts['tip'] ?? $label ),
				'tabindex'    => '0',
			);
		}
		$html = '<span' . self::attrs( $attrs ) . '>' . ( ! empty( $opts['dot'] ) ? '<span class="rooster-admin-badge__dot" aria-hidden="true"></span>' : '' )
			. ( '' !== (string) ( $opts['icon'] ?? '' ) ? Icons::svg( (string) $opts['icon'], 12 ) : '' );
		if ( '' !== (string) ( $opts['href'] ?? '' ) ) {
			$link = array(
				'class' => 'rooster-admin-chip__link' . ( $long ? ' rooster-admin-badge__text' : '' ),
				'href'  => (string) $opts['href'],
			);
			if ( '' !== (string) ( $opts['href_label'] ?? '' ) ) {
				$link += array(
					'aria-label'  => (string) $opts['href_label'],
					'data-ra-tip' => (string) $opts['href_label'],
				);
			}
			$html .= '<a' . self::attrs( $link + ( is_array( $opts['link_attrs'] ?? null ) ? $opts['link_attrs'] : array() ) ) . '>' . esc_html( $label ) . '</a>';
		} else {
			$text  = '' !== (string) ( $opts['html'] ?? '' ) ? (string) $opts['html'] : esc_html( $label );
			$html .= $long ? '<span class="rooster-admin-badge__text">' . $text . '</span>' : $text;
		}
		$html .= (string) ( $opts['after'] ?? '' );
		if ( ! empty( $opts['chip'] ) && '' !== (string) ( $opts['remove'] ?? '' ) ) {
			$html .= '<button' . self::attrs(
				array(
					'type'       => 'button',
					'class'      => 'rooster-admin-chip__remove',
					'aria-label' => (string) $opts['remove'],
				) + ( is_array( $opts['remove_attrs'] ?? null ) ? $opts['remove_attrs'] : array() )
			) . '>' . Icons::ui( 'close', 12 ) . '</button>';
		}
		return $html . '</span>';
	}

	/**
	 * A notice: a page notice (between the cards) or an inline one (inside a card), in a tone, with an optional
	 * title, a dismiss button and actions.
	 *
	 * @param string               $html The text (escaped HTML: `<strong>`, `<a>` allowed by the page's kses).
	 * @param string               $tone info, success, warning, destructive, or mono (a neutral note: nothing to act
	 *                                   on; 0.42.0).
	 * @param array<string, mixed> $opts title (raw), inline, dismissible, detail (escaped HTML: a block under the
	 *                                   text, such as the items an action refused, 0.53.0), actions (escaped HTML), id,
	 *                                   icon (Lucide; default by tone), attrs (a product's data hooks, 0.53.0).
	 */
	public static function notice( string $html, string $tone = 'info', array $opts = array() ): string {
		$tone  = in_array( $tone, array( 'info', 'success', 'warning', 'destructive', 'mono' ), true ) ? $tone : 'info';
		$icons = array(
			'info'        => 'info',
			'success'     => 'circle-check',
			'warning'     => 'triangle-alert',
			'destructive' => 'circle-alert',
			'mono'        => 'message-square',
		);
		$icon  = (string) ( $opts['icon'] ?? $icons[ $tone ] );
		$role  = 'destructive' === $tone || 'warning' === $tone ? 'alert' : 'status';
		$class = 'rooster-admin-notice is-' . $tone . ( ! empty( $opts['inline'] ) ? ' is-inline' : '' );
		$split = self::split_class( $opts['attrs'] ?? null );
		$out   = '<div class="' . esc_attr( $class ) . $split[0] . '" role="' . $role . '"' . ( '' !== (string) ( $opts['id'] ?? '' ) ? ' id="' . esc_attr( (string) $opts['id'] ) . '"' : '' ) . self::attrs( $split[1] ) . '>'
			. ( '' !== $icon ? Icons::svg( $icon, 18, 'rooster-admin-notice__icon' ) : '' ) . '<div class="rooster-admin-notice__body">'
			. ( '' !== (string) ( $opts['title'] ?? '' ) ? '<p class="rooster-admin-notice__title">' . esc_html( (string) $opts['title'] ) . '</p>' : '' )
			. '<p class="rooster-admin-notice__text">' . $html . '</p>'
			. ( '' !== (string) ( $opts['detail'] ?? '' ) ? '<div class="rooster-admin-notice__detail">' . (string) $opts['detail'] . '</div>' : '' )
			. ( '' !== (string) ( $opts['actions'] ?? '' ) ? '<div class="rooster-admin-notice__actions">' . (string) $opts['actions'] . '</div>' : '' ) . '</div>';
		if ( ! empty( $opts['dismissible'] ) ) {
			$out .= '<button type="button" class="rooster-admin-notice__x" data-ra-dismiss="" aria-label="' . esc_attr__( 'Dismiss', 'ai-eshop-optimizer' ) . '">' . Icons::ui( 'close', 14 ) . '</button>';
		}
		return $out . '</div>';
	}

	/**
	 * A tab strip: the page's tabs with counts, the current one marked, an optional secondary row, the library's pin
	 * on the current tab when its catalogue entry is named.
	 *
	 * @param array<int, array<string, mixed>> $tabs   {id, label, url, count (int|null), icon (Lucide), end (true: at
	 *                                                 the strip's end), entry (catalogue id for the pin), attrs (on
	 *                                                 the link: an id, a data-* hook; 0.44.0)}.
	 * @param string                           $active The current tab's id.
	 * @param array<string, mixed>             $opts   sub (a secondary strip), label (the nav's name), class, attrs
	 *                                                 (on the nav; 0.44.0).
	 */
	public static function tabs( array $tabs, string $active, array $opts = array() ): string {
		$split = self::split_class( $opts['attrs'] ?? null );
		$html  = '<nav class="rooster-admin-tabs' . ( ! empty( $opts['sub'] ) ? ' rooster-admin-tabs--sub' : '' ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . esc_attr( (string) $opts['class'] ) : '' ) . $split[0] . '" aria-label="' . esc_attr( (string) ( $opts['label'] ?? __( 'Sections of this page', 'ai-eshop-optimizer' ) ) ) . '"' . self::attrs( $split[1] ) . '><ul class="rooster-admin-tabs__list">';
		foreach ( $tabs as $tab ) {
			if ( ! is_array( $tab ) || '' === (string) ( $tab['label'] ?? '' ) ) {
				continue;
			}
			$id      = (string) ( $tab['id'] ?? sanitize_title( (string) $tab['label'] ) );
			$current = $id === $active;
			$html   .= '<li class="rooster-admin-tabs__item' . ( ! empty( $tab['end'] ) ? ' is-end' : '' ) . '">'
				. '<a class="rooster-admin-tabs__link' . ( $current ? ' is-current' : '' ) . '" href="' . esc_url( (string) ( $tab['url'] ?? '#' ) ) . '"' . ( $current ? ' aria-current="page"' : '' ) . self::attrs( is_array( $tab['attrs'] ?? null ) ? $tab['attrs'] : array() ) . '>'
				. ( '' !== (string) ( $tab['icon'] ?? '' ) ? Icons::svg( (string) $tab['icon'], 15 ) : '' ) . '<span>' . esc_html( (string) $tab['label'] ) . '</span>'
				. ( isset( $tab['count'] ) && null !== $tab['count'] ? '<span class="rooster-admin-tabs__count">' . esc_html( (string) number_format_i18n( (float) $tab['count'] ) ) . '</span>' : '' ) . '</a>';
			if ( $current && '' !== (string) ( $tab['entry'] ?? '' ) && function_exists( 'rooster_admin_pin_button' ) ) {
				$html .= rooster_admin_pin_button( (string) $tab['entry'] );
			}
			$html .= '</li>';
		}
		return $html . '</ul></nav>';
	}

	/**
	 * A field row: the label, the control, the help, the error; stacked or side by side by the container.
	 *
	 * @param array<string, mixed> $field id (the control's id), label (raw), control (escaped HTML), help (raw) or
	 *                                    help_html (escaped HTML; 0.44.0), error (raw), required, group (true: a
	 *                                    group of controls, labelled by a span), pin (escaped HTML), class, attrs
	 *                                    (on the row; 0.44.0), help_id (the help's id, by default the control's id with
	 *                                    `-help`; 0.55.0). Since 0.59.0 (UI-Final-Review FR6, FR7): the help, the error
	 *                                    and the reason are tied to the control (`aria-describedby` on the element whose
	 *                                    id is `id`; on the row itself for a group), never twice; reason (raw: why the
	 *                                    control is disabled, visible right after it, `<id>-reason`; disable the control
	 *                                    in its own builder); parts (a compound row: {label, control, id, attrs (0.84.7)}
	 *                                    per part, Fields::compound(); the row is a group) with joiner (raw: '×', 'to'). Since
	 *                                    0.83.2: wide (true: in a fields grid the row spans every column, `is-wide`: a
	 *                                    control whose choices read whole sentences; elsewhere a row is full width).
	 */
	public static function field_row( array $field ): string {
		$id     = (string) ( $field['id'] ?? '' );
		$label  = (string) ( $field['label'] ?? '' );
		$parts  = is_array( $field['parts'] ?? null ) ? $field['parts'] : array();
		$group  = ! empty( $field['group'] ) || array() !== $parts;
		$error  = (string) ( $field['error'] ?? '' );
		$reason = (string) ( $field['reason'] ?? '' );
		$attrs  = is_array( $field['attrs'] ?? null ) ? $field['attrs'] : array();
		$help   = '' !== (string) ( $field['help_html'] ?? '' ) ? (string) $field['help_html'] : esc_html( (string) ( $field['help'] ?? '' ) );
		$hid    = '' !== $help ? (string) ( $field['help_id'] ?? ( '' !== $id ? $id . '-help' : '' ) ) : '';
		$rid    = '' !== $reason && '' !== $id ? $id . '-reason' : '';
		// FR6, FR7: what describes the control, in reading order: its error, its help, why it is disabled.
		$tied    = array_values( array_filter( array( '' !== $error && '' !== $id ? $id . '-error' : '', $hid, $rid ) ) );
		$control = array() !== $parts ? Fields::compound(
			$parts,
			array(
				'label'  => $label,
				'joiner' => (string) ( $field['joiner'] ?? '' ),
			)
		) : (string) ( $field['control'] ?? '' );
		if ( array() !== $tied && $group ) {
			$attrs['aria-describedby'] = implode( ' ', array_unique( array_merge( preg_split( '/\s+/', trim( (string) ( $attrs['aria-describedby'] ?? '' ) ), -1, PREG_SPLIT_NO_EMPTY ), $tied ) ) );
		} elseif ( array() !== $tied && '' !== $id ) {
			$control = self::describe( $control, $id, $tied );
		}
		$html = '<div class="rooster-admin-field' . ( '' !== $error ? ' is-invalid' : '' ) . ( ! empty( $field['wide'] ) ? ' is-wide' : '' ) . ( '' !== (string) ( $field['class'] ?? '' ) ? ' ' . esc_attr( (string) $field['class'] ) : '' ) . '"' . ( $group && '' !== $id ? ' role="group" aria-labelledby="' . esc_attr( $id ) . '-label"' : '' ) . self::attrs( $attrs ) . '>'
			. '<div class="rooster-admin-field__label">' . ( $group || '' === $id ? '<span' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '-label"' : '' ) . '>' : '<label for="' . esc_attr( $id ) . '">' )
			. esc_html( $label ) . ( ! empty( $field['required'] ) ? ' <span class="rooster-admin-field__required" aria-hidden="true">*</span>' : '' )
			. ( $group || '' === $id ? '</span>' : '</label>' ) . '</div>'
			. '<div class="rooster-admin-field__control">' . $control . ( '' !== $reason ? '<p class="rooster-admin-reason is-essential"' . ( '' !== $rid ? ' id="' . esc_attr( $rid ) . '"' : '' ) . '>' . esc_html( $reason ) . '</p>' : '' ) . '</div>'
			. '<div class="rooster-admin-field__pin">' . (string) ( $field['pin'] ?? '' ) . '</div>';
		if ( '' !== $error ) {
			$html .= '<p class="rooster-admin-field__error"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '-error"' : '' ) . '>' . Icons::svg( 'circle-alert', 14 ) . esc_html( $error ) . '</p>';
		}
		if ( '' !== $help ) {
			$html .= '<p class="rooster-admin-field__help"' . ( '' !== $hid ? ' id="' . esc_attr( $hid ) . '"' : '' ) . '>' . $help . '</p>';
		}
		return $html . '</div>';
	}

	/**
	 * A control's markup with ids added to its `aria-describedby` (0.59.0, FR6): the element whose id is `$id` (an input,
	 * a select, a textarea, a button, or since 0.68.11 a rich text field: any element with role="textbox") keeps what
	 * describes it already and gains the ids it lacks; markup without such an element is returned as it is.
	 *
	 * @param string             $html Escaped HTML.
	 * @param string             $id   The control's id.
	 * @param array<int, string> $ids  The ids that describe it.
	 */
	public static function describe( string $html, string $id, array $ids ): string {
		$pattern = '/<(?:input|select|textarea|button|[a-z][a-z0-9]*(?=[^>]*\srole="textbox"))\b[^>]*\sid="' . preg_quote( esc_attr( $id ), '/' ) . '"[^>]*>/';
		return (string) preg_replace_callback(
			$pattern,
			static function ( array $m ) use ( $ids ): string {
				$tag = $m[0];
				if ( 1 === preg_match( '/\saria-describedby="([^"]*)"/', $tag, $d ) ) {
					$all = array_unique( array_merge( preg_split( '/\s+/', trim( $d[1] ), -1, PREG_SPLIT_NO_EMPTY ), $ids ) );
					return str_replace( $d[0], ' aria-describedby="' . esc_attr( implode( ' ', $all ) ) . '"', $tag );
				}
				return (string) preg_replace( '/\s*\/?>$/', ' aria-describedby="' . esc_attr( implode( ' ', $ids ) ) . '"$0', $tag, 1 );
			},
			$html,
			1
		);
	}

	/**
	 * One filter of a filter bar (`<form class="rooster-admin-filters">`, 0.44.1): its label over its control. The
	 * bar lays the filters on one line, bottom-aligned, with its actions (`rooster-admin-filters__actions`: Apply,
	 * Clear) at the end.
	 *
	 * @param string               $label   The label (raw).
	 * @param string               $control The control (escaped HTML: Ui::select(), Ui::input()).
	 * @param string               $id      The control's id (the label is for it).
	 * @param array<string, mixed> $opts    tip (raw, 0.48.1: why the control is disabled, "Choose an organisation
	 *                                      first", the chrome's tip on the field: a disabled control takes no hover).
	 */
	public static function filter( string $label, string $control, string $id = '', array $opts = array() ): string {
		$tip = (string) ( $opts['tip'] ?? '' );
		return '<div class="rooster-admin-filters__field"' . ( '' !== $tip ? ' data-ra-tip="' . esc_attr( $tip ) . '"' : '' ) . '>'
			. ( '' !== $id ? '<label class="rooster-admin-filters__label" for="' . esc_attr( $id ) . '">' : '<span class="rooster-admin-filters__label">' )
			. esc_html( $label ) . ( '' !== $id ? '</label>' : '</span>' ) . $control . '</div>';
	}

	/**
	 * The attributes a control takes from its options.
	 *
	 * @param string               $name The name.
	 * @param array<string, mixed> $opts id, placeholder, required, disabled, readonly, invalid, help (the help's id
	 *                                   is `<id>-help`), attrs (a class among them is appended to the control's own,
	 *                                   merge_attrs(), 0.84.6).
	 * @return array<string, mixed>
	 */
	private static function control_attrs( string $name, array $opts ): array {
		$id    = (string) ( $opts['id'] ?? $name );
		$attrs = array(
			'id'   => $id,
			'name' => $name,
		);
		// A control without a name is a script's own (a search a script answers, never submitted): no name, and no id
		// unless one is given (0.54.2).
		if ( '' === $name ) {
			unset( $attrs['name'] );
			if ( '' === $id ) {
				unset( $attrs['id'] );
			}
		}
		foreach ( array( 'placeholder', 'autocomplete', 'min', 'max', 'step', 'maxlength', 'pattern', 'inputmode', 'rows', 'aria-label' ) as $key ) { // aria-label: a control without a visible label (a toolbar's search, the second half of a range)
			if ( isset( $opts[ $key ] ) && '' !== (string) $opts[ $key ] ) {
				$attrs[ $key ] = (string) $opts[ $key ];
			}
		}
		foreach ( array( 'required', 'disabled', 'readonly' ) as $flag ) {
			if ( ! empty( $opts[ $flag ] ) ) {
				$attrs[ $flag ] = true;
			}
		}
		if ( ! empty( $opts['invalid'] ) ) {
			$attrs['aria-invalid']     = 'true';
			$attrs['aria-describedby'] = $id . '-error';
		} elseif ( ! empty( $opts['help'] ) ) {
			$attrs['aria-describedby'] = $id . '-help';
		}
		return $attrs + ( is_array( $opts['attrs'] ?? null ) ? $opts['attrs'] : array() );
	}

	/**
	 * A text-like input.
	 *
	 * @param string               $name  The name.
	 * @param string               $value The value.
	 * @param array<string, mixed> $opts  type (text, email, url, number, search, password, date, time, tel; 0.59.0
	 *                                    datetime-local and month: as wide as their value), xs (6rem: a number of up to
	 *                                    four digits, a size in px, a percentage, a duration, a delimiter; 0.59.0), short
	 *                                    (10rem: a number, a code), medium (20rem: a name, a label; 0.43.1), code (a
	 *                                    monospace value; 0.43.0), icon (a leading Lucide icon), unit (raw: a unit after
	 *                                    the field, "minutes", "px", "€"; 0.54.0), class (more classes; 0.59.0), and
	 *                                    control_attrs().
	 */
	public static function input( string $name, string $value = '', array $opts = array() ): string {
		$type  = in_array( $opts['type'] ?? '', array( 'text', 'email', 'url', 'number', 'search', 'password', 'date', 'time', 'tel', 'datetime-local', 'month' ), true ) ? (string) $opts['type'] : 'text';
		$attrs = self::merge_attrs(
			array(
				'type'  => $type,
				'class' => 'rooster-admin-input' . self::width( 'input', $opts ) . ( ! empty( $opts['code'] ) ? ' is-code' : '' ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ),
				'value' => $value,
			),
			self::control_attrs( $name, $opts )
		);
		$input = '<input' . self::attrs( $attrs ) . ' />';
		if ( '' !== (string) ( $opts['icon'] ?? '' ) ) {
			$input = '<span class="rooster-admin-inputwrap">' . Icons::svg( (string) $opts['icon'], 15, 'rooster-admin-inputwrap__icon' ) . $input . '</span>';
		}
		if ( '' !== (string) ( $opts['unit'] ?? '' ) ) {
			$input = '<span class="rooster-admin-unit">' . $input . '<span class="rooster-admin-unit__text">' . esc_html( (string) $opts['unit'] ) . '</span></span>';
		}
		return $input;
	}

	/**
	 * A control's width class (0.59.0, the semantic sizing scale): xs 6rem, short 10rem, medium 20rem; none for the
	 * default (an input 40rem; a select as wide as its longest option, at least 10rem).
	 *
	 * @param string               $kind input or select.
	 * @param array<string, mixed> $opts xs, short, medium (the first set wins).
	 */
	private static function width( string $kind, array $opts ): string {
		foreach ( array( 'xs', 'short', 'medium' ) as $width ) {
			if ( ! empty( $opts[ $width ] ) ) {
				return ' rooster-admin-' . $kind . '--' . $width;
			}
		}
		return '';
	}

	/**
	 * A native select.
	 *
	 * @param string                $name    The name.
	 * @param array<string, string> $options value => label (raw); a nested array is an optgroup (label => options).
	 * @param string                $value   The chosen value.
	 * @param array<string, mixed>  $opts    xs (6rem: a unit, a delimiter), short (10rem), medium (20rem) (0.59.0: a
	 *                                       select is as wide as its longest option by default, at least 10rem; a width
	 *                                       lines it up with its card's other fields), counts (0.65.6: value => how many
	 *                                       rows have it, said after its label, count()), class (0.84.6: more classes), and
	 *                                       control_attrs().
	 */
	public static function select( string $name, array $options, string $value = '', array $opts = array() ): string {
		$counts = is_array( $opts['counts'] ?? null ) ? $opts['counts'] : array();
		unset( $opts['counts'] );
		$attrs = self::merge_attrs( array( 'class' => 'rooster-admin-select' . self::width( 'select', $opts ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ) ), self::control_attrs( $name, $opts ) );
		$html  = '<select' . self::attrs( $attrs ) . '>';
		foreach ( $options as $key => $label ) {
			if ( is_array( $label ) ) {
				$html .= '<optgroup label="' . esc_attr( (string) $key ) . '">';
				foreach ( $label as $k => $l ) {
					$html .= '<option value="' . esc_attr( (string) $k ) . '"' . selected( (string) $k, $value, false ) . '>' . esc_html( (string) $l ) . '</option>';
				}
				$html .= '</optgroup>';
				continue;
			}
			$html .= '<option value="' . esc_attr( (string) $key ) . '"' . selected( (string) $key, $value, false ) . self::counted( (string) $key, (string) $label, $counts ) . '</option>';
		}
		return $html . '</select>';
	}

	/**
	 * How many rows have a choice, as the library says it (0.65.6, Rooster One's request 33): "(12)" after the label,
	 * in the site's number format, as WordPress's own status links say it ("Published (38)"); table-local.js says it the
	 * same way when it counts again.
	 *
	 * @param int $n The rows.
	 */
	public static function count( int $n ): string {
		return '(' . number_format_i18n( $n ) . ')';
	}

	/**
	 * An option's end and its text (escaped): with a count, its plain label and its number for the scripts
	 * (data-ra-label, data-ra-count: the searchable select draws the count apart, a chip says the label) and the count
	 * after the label; else the label.
	 *
	 * @param string             $key    The option's value.
	 * @param string             $label  Its label (raw).
	 * @param array<string, int> $counts value => rows.
	 */
	private static function counted( string $key, string $label, array $counts ): string {
		if ( '' === $key || ! array_key_exists( $key, $counts ) ) {
			return '>' . esc_html( $label );
		}
		$n = (int) $counts[ $key ];
		return ' data-ra-label="' . esc_attr( $label ) . '" data-ra-count="' . $n . '">' . esc_html( $label . ' ' . self::count( $n ) );
	}

	/**
	 * A count after a visible label (a box's, a segment's): the library's one style, the secondary ink, apart from the
	 * label by a margin (a segment is a flex box: a space would go).
	 *
	 * @param string             $key    The choice's value.
	 * @param array<string, int> $counts value => rows.
	 */
	public static function count_tag( string $key, array $counts ): string {
		return '' !== $key && array_key_exists( $key, $counts ) ? '<span class="rooster-admin-count" data-ra-count="' . (int) $counts[ $key ] . '">' . esc_html( self::count( (int) $counts[ $key ] ) ) . '</span>' : '';
	}

	/**
	 * A textarea that grows with its text.
	 *
	 * @param string               $name  The name.
	 * @param string               $value The text.
	 * @param array<string, mixed> $opts  rows (default 4), class (0.84.6: more classes), and control_attrs().
	 */
	public static function textarea( string $name, string $value = '', array $opts = array() ): string {
		$attrs = self::merge_attrs( array( 'class' => 'rooster-admin-textarea' . ( ! empty( $opts['code'] ) ? ' is-code' : '' ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ) ), self::control_attrs( $name, array( 'rows' => (int) ( $opts['rows'] ?? 4 ) ) + $opts ) ); // code: a monospace value (0.43.0)
		return '<textarea' . self::attrs( $attrs ) . '>' . esc_textarea( $value ) . '</textarea>';
	}

	/**
	 * Checkboxes or radios, each with its label, in a grid.
	 *
	 * @param string                $name    The name (`[]` is added for checkboxes).
	 * @param array<string, string> $options value => label (raw).
	 * @param array<int, string>    $values  The chosen values.
	 * @param array<string, mixed>  $opts    type (checkbox, radio), inline (one row), grid (columns of at least 16rem;
	 *                                        0.54.0), descriptions (value => text), counts (0.65.6: value => rows),
	 *                                        switches (0.66.1: each choice a switch, Ui::toggle(), in the same grid and
	 *                                        posting the same `name[]`: a grid of things to turn on, such as trust
	 *                                        badges; checkboxes only).
	 */
	public static function checks( string $name, array $options, array $values = array(), array $opts = array() ): string {
		$radio = 'radio' === ( $opts['type'] ?? '' );
		$html  = '<div class="rooster-admin-checks' . ( ! empty( $opts['inline'] ) ? ' is-inline' : '' ) . ( ! empty( $opts['grid'] ) ? ' is-grid' : '' ) . '">';
		if ( ! $radio && ! empty( $opts['switches'] ) ) {
			foreach ( $options as $value => $label ) {
				$html .= self::toggle(
					$name . '[]',
					in_array( (string) $value, array_map( 'strval', $values ), true ),
					array(
						'id'     => '', // its label wraps it: no id (the name's would repeat)
						'value'  => (string) $value,
						'label'  => (string) $label,
						'hidden' => false, // a list posts the values turned on, as checkboxes do
					)
				);
			}
			return $html . '</div>';
		}
		foreach ( $options as $value => $label ) {
			$desc  = (string) ( $opts['descriptions'][ $value ] ?? '' );
			$html .= '<label class="rooster-admin-check"><input type="' . ( $radio ? 'radio' : 'checkbox' ) . '" name="' . esc_attr( $name . ( $radio ? '' : '[]' ) ) . '" value="' . esc_attr( (string) $value ) . '"' . checked( in_array( (string) $value, array_map( 'strval', $values ), true ), true, false ) . ' />'
				. '<span>' . esc_html( (string) $label ) . self::count_tag( (string) $value, is_array( $opts['counts'] ?? null ) ? $opts['counts'] : array() ) . ( '' !== $desc ? '<small class="rooster-admin-check__desc">' . esc_html( $desc ) . '</small>' : '' ) . '</span></label>';
		}
		return $html . '</div>';
	}

	/**
	 * A switch: a checkbox styled as a toggle, with `role="switch"`.
	 *
	 * @param string               $name The name.
	 * @param bool                 $on   Whether it is on.
	 * @param string               $name The name ('' for a switch a script reads and saves: no name, no hidden 0).
	 * @param bool                 $on   Whether it is on.
	 * @param array<string, mixed> $opts label (raw, beside the switch), label_hidden (the label for screen readers only:
	 *                                   a row's "On"), tip (raw: what the switch does, the chrome's tip on hover and
	 *                                   focus and the input's description; 0.45.5), value (posted when on; default 1:
	 *                                   an array name posts its slug), hidden (false: no hidden 0 before it, for a GET
	 *                                   filter, an array name or a switch a script saves; 0.45.7), id, disabled, attrs.
	 */
	public static function toggle( string $name, bool $on, array $opts = array() ): string {
		$attrs = self::merge_attrs(
			array(
				'type'  => 'checkbox',
				'role'  => 'switch',
				'class' => 'rooster-admin-switch__input',
				'value' => (string) ( $opts['value'] ?? '1' ),
			),
			self::control_attrs( $name, $opts )
		);
		if ( '' === $name ) {
			unset( $attrs['name'] );
		}
		if ( '' === ( $attrs['id'] ?? '' ) ) {
			unset( $attrs['id'] );
		}
		if ( $on ) {
			$attrs['checked'] = true;
		}
		$tip  = (string) ( $opts['tip'] ?? '' );
		$desc = '';
		if ( '' !== $tip && isset( $attrs['id'] ) ) {
			$attrs['aria-describedby'] = $attrs['id'] . '-tip';
			$desc                      = '<span class="screen-reader-text" id="' . esc_attr( $attrs['id'] . '-tip' ) . '">' . esc_html( $tip ) . '</span>';
		}
		$hidden = '' !== $name && false !== ( $opts['hidden'] ?? true ) ? '<input type="hidden" name="' . esc_attr( $name ) . '" value="0" />' : '';
		$label  = (string) ( $opts['label'] ?? '' );
		if ( ! empty( $opts['bare'] ) ) { // 0.63.1: one input drawn as the switch, named by its label (a grid of hundreds)
			$attrs['class']      = 'rooster-admin-switch is-bare';
			$attrs['aria-label'] = $attrs['aria-label'] ?? $label;
			return $hidden . '<input' . self::attrs( $attrs ) . ' />' . $desc;
		}
		return '<label class="rooster-admin-switch"' . ( '' !== $tip ? ' data-ra-tip="' . esc_attr( $tip ) . '"' : '' ) . '>' . $hidden . '<input' . self::attrs( $attrs ) . ' /><span class="rooster-admin-switch__track" aria-hidden="true"><span class="rooster-admin-switch__thumb"></span></span>'
			. ( '' !== $label ? '<span class="rooster-admin-switch__label' . ( ! empty( $opts['label_hidden'] ) ? ' screen-reader-text' : '' ) . '">' . esc_html( $label ) . '</span>' : '' ) . $desc . '</label>';
	}

	/**
	 * An editable cell's content (0.52.0, CONTRACT 8.2 "Editable cells"): the value as shown and the button that opens
	 * its field in place (assets/table-edit.js); a toggle is the kit's switch, saved on change. The caller prints it
	 * only where the viewer may edit the field (else the value alone), gives the row's `<tr>` its `data-ra-row`, and its
	 * script calls roosterTable.edit( frame, { save } ).
	 *
	 * @param string               $shown_html The value as shown (escaped HTML).
	 * @param array<string, mixed> $opts       type (text, number, date, select, toggle), row (the row's id, as its
	 *                                         tr's data-ra-row), key (the field), value (raw: as stored), label (raw: the
	 *                                         field with its row, "Title of Hair basics"), options (select: value =>
	 *                                         label; 0.62.1: or the id of a shared list, Ui::choices(), so 317 cells
	 *                                         carry one list, not 317), min, max, step, maxlength, pattern, required.
	 */
	public static function editable( string $shown_html, array $opts ): string {
		$type  = (string) ( $opts['type'] ?? 'text' );
		$type  = in_array( $type, array( 'text', 'number', 'date', 'select', 'toggle' ), true ) ? $type : 'text';
		$label = (string) ( $opts['label'] ?? '' );
		$attrs = array(
			'class'         => 'rooster-admin-edit' . ( 'toggle' === $type ? ' is-toggle' : '' ),
			'data-ra-edit'  => $type,
			'data-ra-row'   => (string) ( $opts['row'] ?? '' ),
			'data-ra-key'   => (string) ( $opts['key'] ?? '' ),
			'data-ra-value' => (string) ( $opts['value'] ?? '' ),
			'data-ra-label' => $label,
		);
		if ( 'select' === $type && is_string( $opts['options'] ?? null ) ) {
			$attrs['data-ra-options-ref'] = (string) $opts['options']; // a shared list (0.62.1): Ui::choices()
		} elseif ( 'select' === $type ) {
			$attrs['data-ra-options'] = self::pairs( (array) ( $opts['options'] ?? array() ) );
		}
		foreach ( array( 'min', 'max', 'step', 'maxlength', 'pattern' ) as $key ) {
			if ( isset( $opts[ $key ] ) && '' !== (string) $opts[ $key ] ) {
				$attrs[ 'data-ra-' . $key ] = (string) $opts[ $key ];
			}
		}
		if ( ! empty( $opts['required'] ) ) {
			$attrs['data-ra-required'] = '';
		}
		if ( 'toggle' === $type ) { // 0.63.1: the bare switch (about 200 bytes, not 480: a grid repeats it hundreds of times)
			wp_enqueue_script( 'rooster-admin-table-edit' );
			unset( $attrs['data-ra-label'] );
			return '<span' . self::attrs( $attrs ) . '>' . self::toggle(
				'',
				'1' === (string) ( $opts['value'] ?? '' ),
				array(
					'id'    => '',
					'label' => $label,
					'bare'  => true,
					'attrs' => array( 'data-ra-edit-toggle' => '' ),
				)
			) . '</span>';
		}
		wp_enqueue_script( 'rooster-admin-table-edit' ); // its editor, on the screens that print an editable cell only
		/* translators: %s: the field with its row, "Title of Hair basics". */
		$name = sprintf( __( 'Edit %s', 'ai-eshop-optimizer' ), $label );
		return '<span' . self::attrs( $attrs ) . '><span class="rooster-admin-edit__shown">' . $shown_html . '</span>'
			. '<button type="button" class="rooster-admin-edit__open" data-ra-edit-open aria-label="' . esc_attr( $name ) . '" data-ra-tip="' . esc_attr( $name ) . '">' . Icons::ui( 'edit', 14 ) . '</button></span>';
	}

	/**
	 * A table's rows alone, as Ui::table() prints them (0.63.0, CONTRACT §8.2): for a remote table's route (Ui::answer())
	 * and any adapter that draws rows later, so a server's page and the first paint are one markup.
	 *
	 * @param array<int, array<string, mixed>> $columns Ui::table()'s columns.
	 * @param array<int, mixed>                $rows    Ui::table()'s rows.
	 * @param array<string, mixed>             $opts    selectable (each row's checkbox), details (0.64.0: each row's
	 *                                                  Details button and its `_detail` row), move (0.65.0: the
	 *                                                  table's `move`, each row's grip: rows a script draws again),
	 *                                                  cards (0.73.0: the table's `cards`: each cell carries its
	 *                                                  column's name).
	 */
	public static function rows( array $columns, array $rows, array $opts = array() ): string {
		return self::table_rows( array_values( $columns ), $rows, ! empty( $opts['selectable'] ), ! empty( $opts['details'] ), self::move_conf( $opts['move'] ?? null ), ! empty( $opts['cards'] ) );
	}

	/**
	 * Whether a column sorts by a link (0.73.0): the head of a list shown as cards is a row of them.
	 *
	 * @param array<int, array<string, mixed>> $columns The columns.
	 */
	private static function sorts( array $columns ): bool {
		foreach ( $columns as $col ) {
			if ( isset( $col['sort'] ) && '' !== (string) ( $col['sort_url'] ?? '' ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * A table's `move` (0.65.0, rows that move, CONTRACT §8.2), cleaned: null when the table does not move; else
	 * {name (each row's hidden `<name>[]`: the order posts with its form), save ({url, nonce}: each move sent at once),
	 * default (the keys in their default order: Reset to default), label (raw: the list's name)}.
	 *
	 * @param mixed $move true, or the table's options.
	 * @return array<string, mixed>|null
	 */
	private static function move_conf( $move ): ?array {
		if ( true !== $move && ! is_array( $move ) ) {
			return null;
		}
		$move = is_array( $move ) ? $move : array();
		$save = is_array( $move['save'] ?? null ) && '' !== (string) ( $move['save']['url'] ?? '' ) ? $move['save'] : null;
		return array(
			'name'    => preg_replace( '/[^A-Za-z0-9_\[\]-]/', '', (string) ( $move['name'] ?? '' ) ),
			'save'    => null !== $save ? array(
				'url'   => esc_url_raw( (string) $save['url'] ),
				'nonce' => (string) ( $save['nonce'] ?? '' ),
			) : null,
			'default' => array_values( array_map( 'strval', is_array( $move['default'] ?? null ) ? $move['default'] : array() ) ),
			'label'   => (string) ( $move['label'] ?? '' ),
		);
	}

	/**
	 * The frame's attributes of a table whose rows move (0.65.0): the board's ordered list (assets/board.js, loaded
	 * here, so a table that does not move pays nothing): its key, the words of its status line and of its moves, a
	 * declared save, the default order.
	 *
	 * @param array<string, mixed>|null $move move_conf()'s.
	 * @param string                    $id   The table's id (the list's key in the order event).
	 */
	private static function move_attrs( ?array $move, string $id ): string {
		if ( null === $move ) {
			return '';
		}
		wp_enqueue_script( 'rooster-admin-board' );
		$words = array(
			'saved'  => __( 'Saved', 'ai-eshop-optimizer' ),
			/* translators: %s: why it was not saved. */
			'failed' => __( 'Not saved: %s', 'ai-eshop-optimizer' ),
			'back'   => __( 'The row is back where it was.', 'ai-eshop-optimizer' ),
			'off'    => __( 'Clear the sort, the filters and the search to change the order.', 'ai-eshop-optimizer' ),
			'bottom' => __( 'Move to the bottom', 'ai-eshop-optimizer' ),
			'undo'   => __( 'Undo', 'ai-eshop-optimizer' ),
			'undone' => __( 'Undone.', 'ai-eshop-optimizer' ),
		);
		return self::attrs(
			array(
				'data-ra-order'      => $id,
				'data-ra-words'      => (string) wp_json_encode( $words ),
				'data-ra-order-save' => null !== $move['save'] ? (string) wp_json_encode( $move['save'] ) : null,
				'data-ra-default'    => array() !== $move['default'] ? (string) wp_json_encode( $move['default'] ) : null,
				'data-ra-order-name' => '' !== $move['label'] ? $move['label'] : null,
			)
		);
	}

	/**
	 * Under a table whose rows move (0.65.0): its status line ("Saved", or why not; not for an order that posts with
	 * its form, which the card's Unsaved tells) and Reset to default, asked first (the ordered list's).
	 *
	 * @param array<string, mixed> $move    move_conf()'s.
	 * @param string               $id      The table's id.
	 * @param string               $caption The table's caption (the list's name when `label` is not given).
	 * @return array{0: string, 1: string} The footer, and the dialog printed after the table.
	 */
	private static function move_foot( array $move, string $id, string $caption ): array {
		$foot   = '';
		$dialog = '';
		$label  = '' !== $move['label'] ? $move['label'] : ( '' !== $caption ? $caption : __( 'Order', 'ai-eshop-optimizer' ) );
		if ( array() !== $move['default'] ) {
			$foot  .= self::button(
				__( 'Reset to default', 'ai-eshop-optimizer' ),
				array(
					'variant' => 'ghost',
					'size'    => 'sm',
					'icon'    => 'rotate-ccw',
					'attrs'   => array( 'data-ra-dialog' => $id . '-reset' ),
				)
			);
			$dialog = self::dialog(
				$id . '-reset',
				/* translators: %s: the list's name. */
				sprintf( __( 'Reset the order of "%s"?', 'ai-eshop-optimizer' ), $label ),
				'<p>' . esc_html__( 'Every row goes back to its default place. What each row shows is kept.', 'ai-eshop-optimizer' ) . '</p>',
				array(
					'confirm'      => __( 'Reset to default', 'ai-eshop-optimizer' ),
					'dialog_attrs' => array( 'data-ra-order-reset' => $id ),
				)
			);
		}
		if ( '' === $move['name'] || '' !== $foot ) {
			$foot .= '<span class="rooster-admin-olist__status" role="status" aria-live="polite" data-ra-order-status=""></span>';
		}
		return array( '' !== $foot ? '<div class="rooster-admin-table__order">' . $foot . '</div>' : '', $dialog );
	}

	/**
	 * A remote table's answer (0.63.0, CONTRACT §8.2), for the product's route to return as JSON: the page's rows (the
	 * same printer as the first paint), its numbers, the totals over every match, the `<symbol>`s of the icons its rows
	 * use (the page's sprite may lack them; on the storefront there is none), and what the product adds for its own
	 * script (a chart's series: the view event carries it). Nothing in it depends on is_admin(): a storefront table's
	 * route says its context (`context`), as the table sent it.
	 *
	 * @param array<int, array<string, mixed>> $columns Ui::table()'s columns.
	 * @param array<int, mixed>                $rows    The page's rows.
	 * @param array<string, mixed>             $meta    total (every row of the scope), filtered (the rows that match),
	 *                                                  page, per_page, orderby, order.
	 * @param array<string, mixed>             $opts    selectable, totals (key => int|float|string|{html}, over every
	 *                                                  match), extra (any JSON for the product's script).
	 * @return array<string, mixed>
	 */
	public static function answer( array $columns, array $rows, array $meta, array $opts = array() ): array {
		$columns  = array_values( $columns );
		$before   = Icons::used();
		$html     = self::rows( $columns, $rows, $opts );
		$per_page = max( 1, (int) ( $meta['per_page'] ?? count( $rows ) ) );
		$filtered = max( 0, (int) ( $meta['filtered'] ?? $meta['total'] ?? count( $rows ) ) );
		$given    = is_array( $opts['totals'] ?? null ) ? $opts['totals'] : array();
		$totals   = array();
		foreach ( $given as $key => $value ) {
			$totals[ $key ] = Guidance::total( $value ); // a key no column has, as given
		}
		$tones = array();
		foreach ( $columns as $col ) { // 0.65.5: in the column's format; a ratio made from its two totals
			$key  = (string) ( $col['key'] ?? '' );
			$cell = '' !== $key ? self::total_cell( $col, $given ) : array(
				'html' => '',
				'tone' => '',
			);
			if ( '' !== $cell['html'] || array_key_exists( $key, $given ) ) {
				$totals[ $key ] = $cell['html'];
			}
			if ( '' !== $key && ! empty( $col['bands'] ) ) {
				$tones[ $key ] = $cell['tone']; // 0.65.7: its band's tone ('' clears it)
			}
		}
		return array(
			'rows'   => $html,
			'meta'   => array(
				'total'    => max( 0, (int) ( $meta['total'] ?? $filtered ) ),
				'filtered' => $filtered,
				'page'     => max( 1, (int) ( $meta['page'] ?? 1 ) ),
				'per_page' => $per_page,
				'pages'    => max( 1, (int) ceil( $filtered / $per_page ) ),
				'orderby'  => (string) ( $meta['orderby'] ?? '' ),
				'order'    => 'desc' === ( $meta['order'] ?? '' ) ? 'desc' : 'asc',
			),
			'totals' => (object) $totals,
			'tones'  => (object) $tones,
			'icons'  => Icons::symbols( array_merge( array_diff( Icons::used(), $before ), self::answer_icons( $html ) ) ),
			'extra'  => $opts['extra'] ?? null,
		);
	}

	/**
	 * The `<symbol>`s of the icons some markup uses (0.65.1, CONTRACT §8.2 "A table drawn later"): a route that answers a
	 * whole table (Ui::table()) or rows (Ui::rows()) for a product's script sends them beside the HTML, and the script
	 * passes them to roosterAdminTable.enhance( element, icons ), so the page's sprite has every icon the HTML refers to.
	 *
	 * @param string $html Escaped HTML.
	 */
	public static function icons_of( string $html ): string {
		return Icons::symbols( self::answer_icons( $html ) );
	}

	/**
	 * The icons a page of rows refers to, by name (answer_icons()'s list).
	 *
	 * @param string $html The rows.
	 * @return array<int, string>
	 */
	private static function answer_icons( string $html ): array {
		preg_match_all( '/href="#rooster-admin-i-([a-z0-9-]+)"/', $html, $m );
		return $m[1];
	}

	/**
	 * A table's declared save (0.63.0, CONTRACT §8.2 "Editable cells"): its editable cells saved through the product's
	 * route with no script of its own (table-edit.js wires the table: POST {row, key, value, context} with the nonce).
	 *
	 * @param mixed $edit Ui::table()'s `edit`: {url, nonce, open (button, dblclick, click), context}.
	 */
	private static function edit_attrs( $edit ): string {
		if ( ! is_array( $edit ) || '' === (string) ( $edit['url'] ?? '' ) ) {
			return '';
		}
		wp_enqueue_script( 'rooster-admin-table-edit' );
		return self::attrs(
			array(
				'data-ra-edit-url'     => esc_url_raw( (string) $edit['url'] ),
				'data-ra-edit-nonce'   => (string) ( $edit['nonce'] ?? '' ),
				'data-ra-edit-mode'    => in_array( $edit['open'] ?? '', array( 'dblclick', 'click' ), true ) ? (string) $edit['open'] : 'button',
				'data-ra-edit-context' => 'storefront' === ( $edit['context'] ?? '' ) ? 'storefront' : 'admin',
			)
		);
	}

	/**
	 * A shared list of choices for editable select cells (0.62.1): printed once, in the table (Ui::table()'s `choices`)
	 * or anywhere in the page, and named by each cell's `options` (its id), so a grid of 317 selects carries one list,
	 * not 317 (CONTRACT §8.2, the cost measured).
	 *
	 * @param string                $id      The list's id (the cells' `options`).
	 * @param array<string, string> $options value => label (raw), in order.
	 */
	public static function choices( string $id, array $options ): string {
		return '<template data-ra-choices="' . esc_attr( $id ) . '" data-ra-options="' . esc_attr( self::pairs( $options ) ) . '"></template>';
	}

	/**
	 * A select's choices as the editor reads them: a JSON list of [value, label] pairs, its order kept, a numeric key
	 * kept as text, escaped for an attribute by its JSON flags.
	 *
	 * @param array<int|string, mixed> $options value => label (raw).
	 */
	private static function pairs( array $options ): string {
		$pairs = array();
		foreach ( $options as $value => $text ) {
			$pairs[] = array( (string) $value, (string) $text );
		}
		return (string) wp_json_encode( $pairs, JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_TAG );
	}

	/**
	 * The current screen's icon (0.46.8): the Lucide name of its catalogue entry, '' on a screen with no entry (a
	 * record's editor, a Home). For a product that prints its own page head (the LMS's Page::header()), so every
	 * product's head shows the icon its menu bar and catalogue show, as rooster_admin_page_open() heads do.
	 */
	public static function screen_icon(): string {
		$registry = Library::registry();
		$product  = null !== $registry ? $registry->current_product() : '';
		if ( '' === $product ) {
			return '';
		}
		$id    = $registry->current_id( $registry->visible( $product ) );
		$entry = '' !== $id ? $registry->get( $id ) : null;
		return null !== $entry ? (string) ( $entry['icon'] ?? '' ) : '';
	}

	/**
	 * A page's head card (0.46.2): the h1 (an icon before it if asked; a meta badge after its words), the tools at the
	 * far end (an aside such as a language bar, the actions, the pin), the description under it. The one head of every
	 * product's screens (rooster_admin_page_open() prints it). No version beside the title (0.68.21, the owner: "In each
	 * header you display the version of the plugin! It is pointless."; the brand bar and the About screen keep it).
	 * Escaped.
	 *
	 * @param string               $title The title (raw).
	 * @param array<string, mixed> $opts  id (the card's; the h1 is `<id>-title`, a script may rewrite its first text
	 *                                    node), icon (Lucide name; none by default), meta (escaped HTML: a badge),
	 *                                    description (raw), aside, actions, pin (escaped HTML), record (a record's
	 *                                    screen: `is-record`), class (more classes: the section's); since 0.58.0 board
	 *                                    (the key of the page's board: its Reset layout after the actions, shown once
	 *                                    the board has something to move; 0.80.0: its Edit layout before it, shown once
	 *                                    its rows of columns hold two cards or more) and essential (the description stays in the
	 *                                    Compact guidance: a legal duty, data loss, money; FR5).
	 */
	public static function pagehead( string $title, array $opts = array() ): string {
		$id      = (string) ( $opts['id'] ?? '' );
		$icon    = (string) ( $opts['icon'] ?? '' );
		$meta    = (string) ( $opts['meta'] ?? '' );
		$desc    = (string) ( $opts['description'] ?? '' );
		$board   = (string) ( $opts['board'] ?? '' );
		$tools   = (string) ( $opts['aside'] ?? '' ) . (string) ( $opts['actions'] ?? '' ) . ( '' !== $board ? Board::edit_button( $board, true ) . Board::reset_button( $board, true ) : '' ) . (string) ( $opts['pin'] ?? '' );
		$class   = trim( 'rooster-admin-card rooster-admin-pagehead' . ( ! empty( $opts['record'] ) ? ' is-record' : '' ) . ' ' . (string) ( $opts['class'] ?? '' ) );
		return '<div class="' . esc_attr( $class ) . '"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '"' : '' ) . '><div class="rooster-admin-card__head">'
			. '<h1 class="rooster-admin-pagehead__title"' . ( '' !== $id ? ' id="' . esc_attr( $id . '-title' ) . '"' : '' ) . '>'
			. ( '' !== $icon ? Icons::svg( $icon, 22, 'rooster-admin-pagehead__icon' ) : '' ) . esc_html( $title )
			. ( '' !== $meta ? '<span class="rooster-admin-pagehead__meta">' . $meta . '</span>' : '' ) . '</h1>'
			. ( '' !== $tools ? '<div class="rooster-admin-pagehead__actions">' . $tools . '</div>' : '' ) . '</div>'
			. ( '' !== $desc ? '<div class="rooster-admin-card__body"><p class="rooster-admin-card__desc' . ( ! empty( $opts['essential'] ) ? ' is-essential' : '' ) . '">' . esc_html( $desc ) . '</p></div>' : '' )
			. '</div>'; // a div, not a header: the brand bar is the page's banner landmark, the h1 gives the head its structure (axe, 0.26.0)
	}

	/**
	 * A table's text size for the current person (0.68.0, the owner: busy tables, the tiered ones especially): its level,
	 * 1 to 5 (Prefs::TEXT_SIZE_LEVELS: 80, 90, 100, 110 and 125 %), 3 when they chose none or nobody is signed in.
	 *
	 * @param string      $key     The table's key (its DOM id by default).
	 * @param string|null $product The product (null: the current one).
	 */
	public static function text_size( string $key, ?string $product = null ): int {
		$registry = Library::registry();
		$product  = $product ?? ( null !== $registry ? $registry->current_product() : '' );
		$user     = get_current_user_id();
		if ( '' === (string) $product || $user <= 0 ) {
			return 3;
		}
		$level = (int) ( ( (array) Prefs::get( $user, Prefs::TEXT_SIZES, $product, array() ) )[ $key ] ?? 3 );
		return isset( Prefs::TEXT_SIZE_LEVELS[ $level ] ) ? $level : 3;
	}

	/**
	 * A table's text size button (0.68.0), escaped: one icon button that cycles the table through five sizes
	 * (100 → 110 → 125 → 80 → 90 %; Shift goes back) and keeps the choice per person and table (the prefs route's
	 * `text_sizes`). Ui::table()'s `text_size` prints it in its toolbar's end; a product's own table prints it where its
	 * tools are and marks its container with `data-ra-text-size="<Ui::text_size( $key )>"` (the size drawn at first
	 * paint). assets/table-size.js does the rest, loaded by this button only.
	 *
	 * @param string               $target The id of the element it scales (a Ui::table(): its id, the body scaled).
	 * @param array<string, mixed> $opts   key (the table's key for the person's choice; the target by default), label
	 *                                     (raw, with %s for the size: "Text size: %s"), product (the current one by
	 *                                     default), size (0.68.2: `sm`, the default, as a library table's other tools;
	 *                                     `md` beside default-size buttons, the LMS's Expand all). Bordered, as the
	 *                                     tools beside it (0.68.2; it was a ghost button).
	 */
	public static function text_size_button( string $target, array $opts = array() ): string {
		$registry = Library::registry();
		$product  = (string) ( $opts['product'] ?? ( null !== $registry ? $registry->current_product() : '' ) );
		$key      = (string) ( $opts['key'] ?? $target );
		$level    = self::text_size( $key, $product );
		/* translators: %s: the table's text size, "110 %". */
		$label    = (string) ( $opts['label'] ?? __( 'Text size: %s', 'ai-eshop-optimizer' ) );
		$attrs    = array(
			'data-ra-text-size-for'   => $target,
			'data-ra-text-size-key'   => $key,
			'data-ra-text-size-label' => $label,
		);
		if ( get_current_user_id() > 0 && '' !== $product ) { // the person's choice through the prefs route; a visitor's, the browser's
			$attrs += array(
				'data-ra-text-size-rest'    => rest_url( Rest::NAMESPACE . Rest::ROUTE ),
				'data-ra-text-size-nonce'   => wp_create_nonce( 'wp_rest' ),
				'data-ra-text-size-product' => $product,
			);
		}
		wp_enqueue_script( 'rooster-admin-table-size' );
		return self::button(
			sprintf( $label, Prefs::TEXT_SIZE_LEVELS[ $level ] . ' %' ),
			array(
				'size'      => (string) ( $opts['size'] ?? 'sm' ),
				'icon'      => 'a-large-small',
				'icon_only' => true,
				'class'     => 'rooster-admin-table__text-size is-tip-end',
				'attrs'     => $attrs,
			)
		);
	}

	/**
	 * The panels' default layouts on this page (0.67.0): panel_open() records its own, for the builders printed after
	 * it (the open button, the toggle, the tools).
	 *
	 * @var array<string, string>
	 */
	private static array $panel_defaults = array();

	/**
	 * A page's side panel (0.46.0): a helper panel beside the main column (the LMS's courses to drop a lesson on, Rooster
	 * One's chat suggestions). Since 0.67.0 (Rooster One's request 46, the LMS's and the theme's dock pattern) each user
	 * lays it out with the buttons in its head: docked at the start (left) or the end (right) of the main column,
	 * floating over the page (the main column takes the width; the panel moves by its head, resizes from its corner,
	 * folds to its head, and Reset puts it back), or folded away (its open button or toggle brings it back in its last
	 * layout). The state is the user's, per product (Prefs::PANEL_STATE), so the first paint draws the layout; a
	 * floating panel's place is set by assets/panel.js as it loads (hidden until then: no jump). Below 782 px a
	 * floating panel sits in the page above the main column. panel_open() starts the layout and its main column,
	 * panel_side() ends the main column and starts the panel, panel_close() ends both. Escaped.
	 *
	 * @param string               $key  The panel's key (a slug, unique in the product).
	 * @param array<string, mixed> $opts default (the layout before the user chose one: folded, the default, right, left
	 *                                   or floating), width (20rem by default; 0.68.8: medium, 24rem, a step wider,
	 *                                   the LMS's courses; 0.68.0: wide, clamp(20rem, 38%, 40rem), for a panel of
	 *                                   longer words).
	 */
	public static function panel_open( string $key, array $opts = array() ): string {
		$default                       = in_array( $opts['default'] ?? '', Prefs::PANEL_LAYOUTS, true ) ? (string) $opts['default'] : 'folded';
		self::$panel_defaults[ $key ] = $default;
		$state                         = self::panel_state( $key );
		$layout                        = $state['layout'];
		$float                         = 'floating' === $layout;
		wp_enqueue_script( 'rooster-admin-panel' );
		$class = 'rooster-admin-split'
			. ( in_array( $layout, array( 'left', 'right' ), true ) ? ' is-docked' : '' )
			. ( 'left' === $layout ? ' is-left' : '' )
			. ( $float ? ' is-floating' : '' )
			. ( $float && $state['min'] ? ' is-collapsed' : '' )
			. ( $float && null !== $state['x'] ? ' is-placing' : '' ) // hidden until the script puts it in its place
			. ( 'wide' === ( $opts['width'] ?? '' ) ? ' is-wide' : '' )
			. ( 'medium' === ( $opts['width'] ?? '' ) ? ' is-medium' : '' );
		$at    = null !== $state['x'] ? $state['x'] . ',' . $state['y'] . ',' . ( $state['w'] ?? '' ) . ',' . ( $state['h'] ?? '' ) : ( null !== $state['w'] ? ',,' . $state['w'] . ',' . ( $state['h'] ?? '' ) : '' );
		return '<div class="' . esc_attr( $class ) . '" data-ra-panel="' . esc_attr( $key ) . '" data-ra-panel-layout="' . esc_attr( $layout ) . '" data-ra-panel-last="' . esc_attr( $state['last'] ) . '"'
			. ( '' !== $at ? ' data-ra-panel-at="' . esc_attr( $at ) . '"' : '' ) . '><div class="rooster-admin-split__main">';
	}

	/**
	 * The end of the main column and the start of the panel with a bar holding its tools, unless the card the panel
	 * holds carries them (`bar` false).
	 *
	 * @param string               $key   The panel's key.
	 * @param string               $label The panel's name (raw): its region's label.
	 * @param array<string, mixed> $opts  bar (false: no bar; the product prints Ui::panel_tools() in its card's head).
	 */
	public static function panel_side( string $key, string $label, array $opts = array() ): string {
		$bar = false === ( $opts['bar'] ?? true ) ? '' : '<div class="rooster-admin-split__bar">' . self::panel_tools( $key ) . '</div>';
		return '</div><aside class="rooster-admin-split__side" id="' . esc_attr( 'rooster-admin-panel-' . $key ) . '" aria-label="' . esc_attr( $label ) . '" tabindex="-1" data-ra-panel-side="">'
			. $bar . '<div class="rooster-admin-split__body">';
	}

	/**
	 * The panel's open button (0.47.1, the owner: "in the section itself, in the respective position of the pin"): an
	 * icon button for the head of the main column's card, beside its pin; it brings a folded panel back in its last
	 * layout and hides while the panel shows. Escaped.
	 *
	 * @param string $key   The panel's key.
	 * @param string $label The button's name (raw: "Show the courses").
	 */
	public static function panel_open_button( string $key, string $label ): string {
		return self::button(
			$label,
			array(
				'variant'   => 'ghost',
				'size'      => 'sm',
				'icon'      => 'panel-right-open',
				'icon_only' => true,
				'class'     => 'rooster-admin-split__open is-tip-end',
				'attrs'     => array(
					'aria-controls'        => 'rooster-admin-panel-' . $key,
					'aria-expanded'        => self::panel_docked( $key ) ? 'true' : 'false',
					'data-ra-panel-toggle' => $key,
				),
			)
		);
	}

	/**
	 * The panel's tools, escaped: the panel's bar, or the tools of the card the panel holds, so they sit in the card's
	 * head as every card's tools. Since 0.67.0: while it floats, its grip (the arrow keys move it, Shift and an arrow
	 * resize it; the head drags it), Fold to its head and Reset; always the three layouts (docked at the start, at the
	 * end, floating: the theme's order), pressed for the one drawn; last, Fold the panel away.
	 *
	 * @param string $key The panel's key.
	 */
	public static function panel_tools( string $key ): string {
		$state = self::panel_state( $key );
		$tool  = static fn( string $label, string $icon, array $attrs ): string => self::button(
			$label,
			array(
				'variant'   => 'ghost',
				'size'      => 'sm',
				'icon'      => $icon,
				'icon_only' => true,
				'class'     => 'rooster-admin-split__tool is-tip-end',
				'attrs'     => $attrs + array( 'aria-controls' => 'rooster-admin-panel-' . $key ),
			)
		);
		$html  = '<span class="rooster-admin-split__float-tools">'
			. $tool( __( 'Move the panel: the arrow keys (Shift and an arrow key resizes it), or drag its head', 'ai-eshop-optimizer' ), 'grip-vertical', array( 'data-ra-panel-grip' => '' ) )
			. $tool( __( 'Fold the panel to its head', 'ai-eshop-optimizer' ), 'chevron-up', array( 'data-ra-panel-collapse' => '', 'aria-expanded' => $state['min'] ? 'false' : 'true' ) )
			. $tool( __( 'Put the panel back in its place', 'ai-eshop-optimizer' ), 'rotate-ccw', array( 'data-ra-panel-reset' => '' ) )
			. '</span><span class="rooster-admin-split__layouts" role="group" aria-label="' . esc_attr__( 'Panel layout', 'ai-eshop-optimizer' ) . '" data-ra-panel-layouts="">';
		foreach ( array(
			'left'     => array( __( 'Dock at the start', 'ai-eshop-optimizer' ), 'panel-left' ),
			'right'    => array( __( 'Dock at the end', 'ai-eshop-optimizer' ), 'panel-right' ),
			'floating' => array( __( 'Float over the page', 'ai-eshop-optimizer' ), 'picture-in-picture-2' ),
		) as $layout => $words ) {
			$html .= $tool( $words[0], $words[1], array( 'data-ra-panel-to' => $layout, 'aria-pressed' => $layout === $state['layout'] ? 'true' : 'false' ) );
		}
		$html .= '</span>';
		return $html . self::button(
			__( 'Fold the panel away', 'ai-eshop-optimizer' ),
			array(
				'variant'   => 'ghost',
				'size'      => 'sm',
				'icon'      => 'x',
				'icon_only' => true,
				'class'     => 'rooster-admin-split__close is-tip-end',
				'attrs'     => array(
					'aria-controls'       => 'rooster-admin-panel-' . $key,
					'data-ra-panel-close' => '',
				),
			)
		);
	}

	/**
	 * The end of the panel and of the layout.
	 */
	public static function panel_close(): string {
		return '</div></aside></div>';
	}

	/**
	 * The panel's toggle (0.47.1, the owner: "it can be like a toggle"): the kit's switch with the panel's name, on
	 * while the panel shows (docked or floating); switching it on brings the panel back in its last layout, off folds
	 * it away, per user. Escaped.
	 *
	 * @param string $key   The panel's key.
	 * @param string $label The switch's words (raw: the panel's name, "Courses").
	 */
	public static function panel_toggle( string $key, string $label ): string {
		return self::toggle(
			'',
			self::panel_docked( $key ),
			array(
				'label' => $label,
				'id'    => 'rooster-admin-panel-toggle-' . $key,
				'attrs' => array(
					'aria-controls'        => 'rooster-admin-panel-' . $key,
					'data-ra-panel-toggle' => $key,
				),
			)
		);
	}

	/**
	 * Whether the current user's panel shows (docked or floating; not folded away).
	 *
	 * @param string $key The panel's key.
	 */
	public static function panel_docked( string $key ): bool {
		return 'folded' !== self::panel_state( $key )['layout'];
	}

	/**
	 * The current user's state of a panel (0.67.0): theirs (Prefs::PANEL_STATE), else docked on the right when the
	 * panel is among the docked ones of before (Prefs::PANELS), else its default (panel_open()'s `default`, folded when
	 * it gave none).
	 *
	 * @param string      $key     The panel's key.
	 * @param string|null $default The default layout (null: panel_open()'s, else folded).
	 * @return array{layout: string, last: string, x: ?int, y: ?int, w: ?int, h: ?int, min: bool}
	 */
	public static function panel_state( string $key, ?string $default = null ): array {
		$default  = $default ?? ( self::$panel_defaults[ $key ] ?? 'folded' );
		$default  = in_array( $default, Prefs::PANEL_LAYOUTS, true ) ? $default : 'folded';
		$out      = array(
			'layout' => $default,
			'last'   => 'folded' === $default ? 'right' : $default,
			'x'      => null,
			'y'      => null,
			'w'      => null,
			'h'      => null,
			'min'    => false,
		);
		$registry = Library::registry();
		$product  = null !== $registry ? $registry->current_product() : '';
		$user     = get_current_user_id();
		if ( '' === $product || $user <= 0 ) {
			return $out;
		}
		$all   = (array) Prefs::get( $user, Prefs::PANEL_STATE, $product, array() );
		$state = isset( $all[ $key ] ) ? Prefs::clean_panel( $all[ $key ] ) : null;
		if ( null !== $state ) {
			return $state;
		}
		if ( in_array( $key, (array) Prefs::get( $user, Prefs::PANELS, $product, array() ), true ) ) {
			$out['layout'] = 'right';
			$out['last']   = 'right';
		}
		return $out;
	}

	/**
	 * A page's windows (0.68.13, Rooster One's request 52; the owner: "un/dockable, re-arrangeable … like the side bar
	 * is", several on one page). Each window has the side panel's tools in its head: dock it at the start or the end of
	 * the row, float it over the page, fold it away. Docked windows are the row's columns in the user's order: the main
	 * one takes the rest of the width and the others keep theirs (when the main one is not docked, they share it). The
	 * user reorders them by dragging a head, or with the grip's arrow keys. A floating window moves by its head, resizes
	 * from its corner, folds to its head, comes on top when touched and stays in the browser window under the bars;
	 * Reset puts it back. A folded window's Show button waits on a line above the row (and a floating one's Dock while
	 * none is docked), so the page never keeps an empty hole. The state is the user's, per product and layout
	 * (Prefs::WINDOWS): the server prints the windows in the user's order and layouts (no jump, no inline style), and
	 * assets/windows.js switches them without re-creating a window's content (a reorder moves the window's own element,
	 * its scroll and focus kept). Below 960 px the docked windows stack in their order; below 782 px the floating ones
	 * join them. An element with `rooster-admin-window__fill` in a card's body (a transcript) takes the free height of a
	 * window whose height is bounded (floating, or docked beside the main one) and scrolls, the card's footer and the
	 * other parts staying at its foot. Escaped.
	 *
	 * @param string                           $key     The layout's key (a slug, unique in the product).
	 * @param array<int, array<string, mixed>> $windows In their default order: {key (a slug, unique in the layout),
	 *                                                  label (raw: its name, in its tools and on the line), html (its
	 *                                                  content, escaped: a callable given the window's tools, escaped, to
	 *                                                  put in its card's head, returning the card; or a string, whose
	 *                                                  tools go on a bar of their own above it), main (true: it takes the
	 *                                                  rest of the row; the first such window), width ('' 20rem, medium
	 *                                                  24rem, wide clamp(20rem, 38%, 40rem): its column docked, its first
	 *                                                  width floating), default (docked, floating or folded: the layout
	 *                                                  before the user chose one; docked by default)}.
	 */
	public static function windows( string $key, array $windows ): string {
		$slug = '/^[a-z0-9][a-z0-9_-]{0,39}$/';
		if ( 1 !== preg_match( $slug, $key ) ) {
			return '';
		}
		$decl = array();
		$main = '';
		foreach ( $windows as $window ) {
			$name = is_array( $window ) ? (string) ( $window['key'] ?? '' ) : '';
			if ( 1 !== preg_match( $slug, $name ) || isset( $decl[ $name ] ) || count( $decl ) >= Prefs::MAX_WINDOWS ) {
				continue;
			}
			$main           = '' === $main && ! empty( $window['main'] ) ? $name : $main;
			$decl[ $name ] = $window;
		}
		if ( array() === $decl ) {
			return '';
		}
		$saved  = self::windows_saved( $key );
		$order  = array_values( array_intersect( $saved['o'], array_keys( $decl ) ) );
		$order  = array_merge( $order, array_values( array_diff( array_keys( $decl ), $order ) ) ); // a window new to the user at the end
		$states = array();
		foreach ( $decl as $name => $window ) {
			$default         = in_array( $window['default'] ?? '', Prefs::WINDOW_LAYOUTS, true ) ? (string) $window['default'] : 'docked';
			$states[ $name ] = $saved['s'][ $name ] ?? array(
				'layout' => $default,
				'last'   => 'folded' === $default ? 'docked' : $default,
				'x'      => null,
				'y'      => null,
				'w'      => null,
				'h'      => null,
				'min'    => false,
			);
		}
		$docked = array_values( array_filter( $order, static fn( string $name ): bool => 'docked' === $states[ $name ]['layout'] ) );
		$many   = count( $decl ) > 1;
		wp_enqueue_script( 'rooster-admin-windows' );
		$tray = '';
		$row  = '';
		foreach ( $order as $at => $name ) {
			$window = $decl[ $name ];
			$state  = $states[ $name ];
			$label  = (string) ( $window['label'] ?? $name );
			$id     = 'rooster-admin-window-' . $key . '-' . $name;
			$layout = $state['layout'];
			$float  = 'floating' === $layout;
			$place  = $layout;
			if ( 'docked' === $layout ) { // pressed: the first or the last of the docked ones (alone: its side of the order)
				$i     = (int) array_search( $name, $docked, true );
				$place = count( $docked ) > 1 ? ( 0 === $i ? 'start' : ( count( $docked ) - 1 === $i ? 'end' : '' ) ) : ( 0 === $at ? 'start' : 'end' );
			}
			$tool   = static fn( string $words, string $icon, array $attrs ): string => self::button(
				$words,
				array(
					'variant'   => 'ghost',
					'size'      => 'sm',
					'icon'      => $icon,
					'icon_only' => true,
					'class'     => 'rooster-admin-window__tool is-tip-end',
					'attrs'     => $attrs + array( 'aria-controls' => $id ),
				)
			);
			/* translators: %s: the window's name. */
			$grip  = $tool( sprintf( __( 'Move %s: drag its head, or use the arrow keys (Shift and an arrow key resizes it while it floats)', 'ai-eshop-optimizer' ), $label ), 'grip-vertical', array( 'data-ra-window-grip' => '' ) );
			$tools = ( $many ? $grip : '' ) . '<span class="rooster-admin-window__float-tools">' . ( $many ? '' : $grip )
				/* translators: %s: the window's name. */
				. $tool( sprintf( __( 'Fold %s to its head', 'ai-eshop-optimizer' ), $label ), 'chevron-up', array( 'data-ra-window-collapse' => '', 'aria-expanded' => $state['min'] ? 'false' : 'true' ) )
				/* translators: %s: the window's name. */
				. $tool( sprintf( __( 'Put %s back in its place', 'ai-eshop-optimizer' ), $label ), 'rotate-ccw', array( 'data-ra-window-reset' => '' ) )
				/* translators: %s: the window's name. */
				. '</span><span class="rooster-admin-window__layouts" role="group" aria-label="' . esc_attr( sprintf( __( 'Layout of %s', 'ai-eshop-optimizer' ), $label ) ) . '" data-ra-window-layouts="">';
			foreach ( array(
				/* translators: %s: the window's name. */
				'start'    => array( __( 'Dock %s at the start', 'ai-eshop-optimizer' ), 'panel-left' ),
				/* translators: %s: the window's name. */
				'end'      => array( __( 'Dock %s at the end', 'ai-eshop-optimizer' ), 'panel-right' ),
				/* translators: %s: the window's name. */
				'floating' => array( __( 'Float %s over the page', 'ai-eshop-optimizer' ), 'picture-in-picture-2' ),
			) as $to => $words ) {
				$tools .= $tool( sprintf( $words[0], $label ), $words[1], array( 'data-ra-window-to' => $to, 'aria-pressed' => $to === $place ? 'true' : 'false' ) );
			}
			/* translators: %s: the window's name. */
			$tools .= '</span>' . $tool( sprintf( __( 'Fold %s away', 'ai-eshop-optimizer' ), $label ), 'x', array( 'data-ra-window-close' => '' ) );
			$html   = $window['html'] ?? '';
			$bar    = is_string( $html ) || ! is_callable( $html ); // a string is content, never a function's name
			$html   = $bar ? (string) $html : (string) $html( $tools );
			$class  = 'rooster-admin-window is-' . $layout
				. ( $name === $main ? ' is-main' : '' )
				. ( in_array( $window['width'] ?? '', array( 'wide', 'medium' ), true ) ? ' is-' . $window['width'] : '' )
				. ( $float && $state['min'] ? ' is-collapsed' : '' )
				. ( $float && null !== $state['x'] ? ' is-placing' : '' ) // hidden until the script puts it in its place
				. ( $bar ? ' has-bar' : '' )
				. ( false !== strpos( $html, 'rooster-admin-window__fill' ) ? ' has-fill' : '' ) // a part that takes the free height
				. ( array() !== $docked && end( $docked ) === $name ? ' is-end' : '' ); // 0.68.16: the last docked one, its gutter between the columns
			$at_px  = null !== $state['x'] ? $state['x'] . ',' . $state['y'] . ',' . ( $state['w'] ?? '' ) . ',' . ( $state['h'] ?? '' ) : ( null !== $state['w'] ? ',,' . $state['w'] . ',' . ( $state['h'] ?? '' ) : '' );
			$row   .= '<div' . self::attrs(
				array(
					'class'               => $class,
					'id'                  => $id,
					'tabindex'            => '-1',
					'data-ra-window'      => $name,
					'data-ra-window-name' => $label,
					'data-ra-window-last' => $state['last'],
					'data-ra-window-at'   => '' !== $at_px ? $at_px : null,
				)
			) . '>' . ( $bar ? '<div class="rooster-admin-window__bar"><span class="rooster-admin-window__title">' . esc_html( $label ) . '</span>' . $tools . '</div>' : '' )
				. '<div class="rooster-admin-window__body">' . $html . '</div></div>';
			// Its buttons on the line above the row: Show while it is folded away, Dock while it floats and none is docked.
			$tray .= self::button(
				/* translators: %s: the window's name. */
				sprintf( __( 'Show %s', 'ai-eshop-optimizer' ), $label ),
				array(
					'variant' => 'ghost',
					'size'    => 'sm',
					'icon'    => 'panel-right-open',
					'class'   => 'rooster-admin-windows__show',
					'attrs'   => array(
						'aria-controls'       => $id,
						'data-ra-window-show' => $name,
						'hidden'              => 'folded' !== $layout,
					),
				)
			) . self::button(
				/* translators: %s: the window's name. */
				sprintf( __( 'Dock %s', 'ai-eshop-optimizer' ), $label ),
				array(
					'variant' => 'ghost',
					'size'    => 'sm',
					'icon'    => 'panel-left',
					'class'   => 'rooster-admin-windows__show',
					'attrs'   => array(
						'aria-controls'       => $id,
						'data-ra-window-dock' => $name,
						'hidden'              => ! ( $float && array() === $docked ),
					),
				)
			);
		}
		$lined = array() === $docked || in_array( 'folded', array_column( $states, 'layout' ), true );
		$words = array(
			/* translators: 1: the window's name, 2: its place among the docked windows, 3: how many are docked. */
			'moved' => __( '%1$s: place %2$d of %3$d', 'ai-eshop-optimizer' ),
		);
		return '<div' . self::attrs(
			array(
				'class'            => 'rooster-admin-windows' . ( '' !== $main && 'docked' === $states[ $main ]['layout'] ? ' has-main' : '' ) . ( count( $docked ) > 1 ? ' is-many' : '' ),
				'id'               => 'rooster-admin-windows-' . $key,
				'data-ra-windows'  => $key,
				'data-ra-words'    => (string) wp_json_encode( $words ),
			)
		) . '><div class="rooster-admin-windows__tray"' . ( $lined ? '' : ' hidden' ) . '>' . $tray . '</div><div class="rooster-admin-windows__row">' . $row . '</div></div>';
	}

	/**
	 * The current user's windows of a layout (0.68.13, Prefs::WINDOWS, cleaned), else none.
	 *
	 * @param string $key The layout's key.
	 * @return array{o: list<string>, s: array<string, array<string, mixed>>}
	 */
	private static function windows_saved( string $key ): array {
		$none     = array(
			'o' => array(),
			's' => array(),
		);
		$product = Library::product(); // 0.75.0: the registry's, or the storefront screen's
		$user    = get_current_user_id();
		if ( '' === $product || $user <= 0 ) {
			return $none;
		}
		$all = (array) Prefs::get( $user, Prefs::WINDOWS, $product, array() );
		return isset( $all[ $key ] ) ? ( Prefs::clean_windows( $all[ $key ] ) ?? $none ) : $none;
	}

	/**
	 * A row's actions (0.45.9): text links (or buttons, for an action a script runs) under the row's title, always
	 * shown, a destructive one in the destructive ink. Each control carries `rooster-admin-table__action`, so the dark
	 * scheme's link colour leaves it alone. Escaped.
	 *
	 * @param array<int, array<string, mixed>> $items {label (raw), url ('' with button: a <button type="button">),
	 *                                                destructive, attrs (more attributes: data-* for a script, a
	 *                                                confirmation)}.
	 */
	public static function row_actions( array $items ): string {
		$html = '';
		foreach ( $items as $item ) {
			$label = (string) ( $item['label'] ?? '' );
			if ( '' === $label ) {
				continue;
			}
			$attrs = array( 'class' => 'rooster-admin-table__action' . ( ! empty( $item['destructive'] ) ? ' is-destructive' : '' ) ) + ( is_array( $item['attrs'] ?? null ) ? $item['attrs'] : array() );
			$url   = (string) ( $item['url'] ?? '' );
			if ( '' !== $url ) {
				$html .= '<a' . self::attrs( array( 'href' => $url ) + $attrs ) . '>' . esc_html( $label ) . '</a>';
			} elseif ( ! empty( $item['button'] ) ) {
				$html .= '<button' . self::attrs( array( 'type' => 'button' ) + $attrs ) . '>' . esc_html( $label ) . '</button>';
			}
		}
		return '' === $html ? '' : '<div class="rooster-admin-table__actions">' . $html . '</div>';
	}

	/**
	 * A row's menu (0.79.0; Rooster LMS's request, the owner's go of 6 Nov 2026: "the dotted edit column", for this
	 * action "and potentially other actions in the future"): a small icon-only "⋮" button named "Actions for <name>"
	 * that opens the row's actions as a list (a popover, role menu), in a table's actions column (FR17: the last; one
	 * control, so the cell never wraps) or on its own (a card's head, beside a record's facts). The server prints the
	 * button and the list, so the first paint is the final one; assets/row-menu.js and assets/row-menu.css (loaded here; a
	 * page whose rows a script or a REST answer draws later asks for them with rooster_admin_table_assets( array(
	 * 'row-menu' ) ))
	 * place the list under its button inside the window, above it where the room below is short, and give it the
	 * menu's keys. Without the script the browser's popover still opens it in the window's middle, closes it on Escape
	 * and a click outside, and Tab walks its items. Escaped.
	 *
	 * @param array<int, array<string, mixed>> $items {label (raw), url (a link: a state change is a GET with its nonce)
	 *                                                or none (a button a script answers), destructive (the destructive
	 *                                                ink; sorted last, after a line), description (raw: what it does,
	 *                                                a line under the label, its accessible description), disabled,
	 *                                                reason (raw: why it cannot act now, FR7: a line under the label;
	 *                                                disables it: still reached by the arrows, aria-disabled, no link
	 *                                                and no attrs but its id), icon (Lucide), group (raw: a heading over
	 *                                                the run of items that share it), attrs (data-* for a script, a
	 *                                                confirmation: States::confirm_attrs()), dialog (escaped HTML: the
	 *                                                item's own dialog, printed after the list, never inside it: a
	 *                                                closed list would hide it)}.
	 * @param array<string, mixed>             $opts  name (raw: what the actions act on; the button is named "Actions
	 *                                                for <name>"), label (raw: the button's whole name instead; default
	 *                                                "Actions"), id (the list's id; a unique one by default).
	 */
	public static function row_menu( array $items, array $opts = array() ): string {
		$items = array_values( array_filter( $items, static fn( $item ): bool => is_array( $item ) && '' !== (string) ( $item['label'] ?? '' ) ) );
		if ( array() === $items ) {
			return '';
		}
		usort( $items, static fn( array $a, array $b ): int => (int) ! empty( $a['destructive'] ) <=> (int) ! empty( $b['destructive'] ) ); // stable since PHP 8.0: the given order kept within each kind
		$id   = '' !== (string) ( $opts['id'] ?? '' ) ? (string) $opts['id'] : wp_unique_id( 'rooster-admin-rowmenu-' );
		$row  = (string) ( $opts['name'] ?? '' );
		$name = (string) ( $opts['label'] ?? '' );
		if ( '' === $name ) {
			/* translators: %s: what the actions act on (a row's name: "Lesson 3"). */
			$name = '' !== $row ? sprintf( __( 'Actions for %s', 'ai-eshop-optimizer' ), $row ) : __( 'Actions', 'ai-eshop-optimizer' );
		}
		// The items in runs: a run is the items of one group, the destructive ones always a run of their own; a line
		// between two runs, a run with a group's name a group under its heading (the heading is the group's name).
		$list    = '';
		$dialogs = '';
		$run     = null;
		$grouped = false;
		foreach ( $items as $i => $item ) {
			$group = (string) ( $item['group'] ?? '' );
			$key   = ( ! empty( $item['destructive'] ) ? 'd' : 'n' ) . '|' . $group;
			if ( $key !== $run ) {
				$list   .= ( $grouped ? '</div>' : '' ) . ( null !== $run ? '<div class="rooster-admin-rowmenu__sep" role="separator"></div>' : '' );
				$grouped = '' !== $group;
				$list   .= $grouped ? '<div class="rooster-admin-rowmenu__group" role="group" aria-label="' . esc_attr( $group ) . '"><span class="rooster-admin-rowmenu__head" aria-hidden="true">' . esc_html( $group ) . '</span>' : '';
				$run     = $key;
			}
			$list    .= self::row_menu_item( $item, $id . '-' . $i );
			$dialogs .= (string) ( $item['dialog'] ?? '' );
		}
		$list  .= $grouped ? '</div>' : '';
		$button = self::button(
			$name,
			array(
				'variant'   => 'ghost',
				'size'      => 'sm',
				'icon'      => 'ellipsis-vertical',
				'icon_only' => true,
				'class'     => 'rooster-admin-rowmenu__button',
				'attrs'     => array(
					'popovertarget' => $id,
					'aria-haspopup' => 'menu',
					'aria-expanded' => 'false',
					'aria-controls' => $id,
				),
			)
		);
		if ( function_exists( 'wp_enqueue_script' ) ) {
			wp_enqueue_script( 'rooster-admin-row-menu' ); // its keys and its place, on the screens that print a menu only
			wp_enqueue_style( 'rooster-admin-row-menu' ); // its list's look (the wrapper's one rule is the chrome's: the first paint)
		}
		return '<div class="rooster-admin-rowmenu" data-ra-rowmenu="">' . $button
			. '<div class="rooster-admin-rowmenu__list" id="' . esc_attr( $id ) . '" popover="auto" role="menu" aria-label="' . esc_attr( $name ) . '">' . $list . '</div>'
			. $dialogs . '</div>';
	}

	/**
	 * One item of a row's menu (row_menu()): a link, or a button a script answers; a disabled one a button that does
	 * nothing, reached by the arrows so its reason is read.
	 *
	 * @param array<string, mixed> $item See row_menu().
	 * @param string               $id   The item's id prefix (its note's id is `<id>-note`).
	 */
	private static function row_menu_item( array $item, string $id ): string {
		$reason   = (string) ( $item['reason'] ?? '' );
		$disabled = ! empty( $item['disabled'] ) || '' !== $reason;
		$note     = $disabled && '' !== $reason ? $reason : (string) ( $item['description'] ?? '' );
		$given    = is_array( $item['attrs'] ?? null ) ? $item['attrs'] : array();
		$given    = $disabled ? array_intersect_key( $given, array( 'id' => true ) ) : $given; // a disabled item does nothing: no script's hook, no confirmation
		$attrs    = array(
			'class' => 'rooster-admin-rowmenu__item' . ( ! empty( $item['destructive'] ) ? ' is-destructive' : '' ) . ( $disabled ? ' is-disabled' : '' ),
			'role'  => 'menuitem',
		);
		$text     = '<span class="rooster-admin-rowmenu__label">' . esc_html( (string) $item['label'] ) . '</span>';
		if ( '' !== $note ) {
			// The note is the item's description, not part of its name (aria-hidden: the name stays the label).
			$attrs['aria-describedby'] = trim( (string) ( $given['aria-describedby'] ?? '' ) . ' ' . $id . '-note' );
			$text                     .= '<span class="rooster-admin-rowmenu__note" id="' . esc_attr( $id . '-note' ) . '" aria-hidden="true">' . esc_html( $note ) . '</span>';
		}
		$attrs += $given;
		$inner  = ( '' !== (string) ( $item['icon'] ?? '' ) ? Icons::svg( (string) $item['icon'], 15, 'rooster-admin-rowmenu__icon' ) : '' ) . '<span class="rooster-admin-rowmenu__text">' . $text . '</span>';
		$url    = (string) ( $item['url'] ?? '' );
		if ( $disabled ) {
			return '<button' . self::attrs( array( 'type' => 'button' ) + $attrs + array( 'aria-disabled' => 'true' ) ) . '>' . $inner . '</button>';
		}
		if ( '' !== $url ) {
			return '<a' . self::attrs( array( 'href' => $url ) + $attrs ) . '>' . $inner . '</a>';
		}
		return '<button' . self::attrs( array( 'type' => 'button' ) + $attrs ) . '>' . $inner . '</button>';
	}

	/**
	 * A combobox:a native select the chrome's script upgrades to the kit's searchable select (assets/select.js,
	 * 0.36.0: type-ahead, keyboard, chips for multiple, select all and clear, server search); without the script a
	 * native select. The select stays the form value.
	 *
	 * @param string               $name    The name (`[]` is added for multiple).
	 * @param array<string, mixed> $options value => label (raw), or group label => [value => label].
	 * @param string|string[]      $value   The chosen value(s).
	 * @param array<string, mixed> $opts    placeholder, id, multiple, summary (a multiple select that reads like a
	 *                                      single one and sums its choice up: a filter), search (a URL with {q}: the
	 *                                      options come from the server), method (get|post), nonce (REST), items
	 *                                      (key of the result list), value_key, label_key, meta_key, control_attrs();
	 *                                      0.59.0: xs, short, medium (the combobox's width, as select()'s; a multiple
	 *                                      one is medium to the default 40rem); counts (0.65.6: value => rows).
	 */
	public static function combo( string $name, array $options, $value = '', array $opts = array() ): string {
		$counts   = is_array( $opts['counts'] ?? null ) ? $opts['counts'] : array();
		unset( $opts['counts'] );
		$multiple = ! empty( $opts['multiple'] );
		$values   = array_map( 'strval', is_array( $value ) ? $value : array( $value ) );
		$attrs    = self::merge_attrs(
			array(
				'class'         => 'rooster-admin-select' . self::width( 'select', $opts ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ),
				'data-ra-combo' => '',
			),
			self::control_attrs( $name, array( 'id' => (string) ( $opts['id'] ?? rtrim( $name, '[]' ) ) ) + $opts )
		);
		if ( $multiple ) {
			$attrs['multiple'] = true;
			if ( '' !== $name ) { // a nameless one is a script's own (0.64.2: a form grid's filter), never "[]"
				$attrs['name'] = str_ends_with( $name, '[]' ) ? $name : $name . '[]';
			}
		}
		if ( ! empty( $opts['summary'] ) ) {
			$attrs['data-ra-summary'] = '';
		}
		unset( $attrs['placeholder'] );
		if ( '' !== (string) ( $opts['placeholder'] ?? '' ) ) {
			$attrs['data-placeholder'] = (string) $opts['placeholder'];
		}
		foreach ( array( 'search' => 'data-ra-search', 'method' => 'data-ra-search-method', 'nonce' => 'data-ra-nonce', 'items' => 'data-ra-search-items', 'value_key' => 'data-ra-search-value', 'label_key' => 'data-ra-search-label', 'meta_key' => 'data-ra-search-meta' ) as $key => $attr ) { // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- not a query: the search's data attributes, by option name.
			if ( '' !== (string) ( $opts[ $key ] ?? '' ) ) {
				$attrs[ $attr ] = (string) $opts[ $key ];
			}
		}
		$option = static function ( string $key, string $label ) use ( $values, $counts ): string {
			return '<option value="' . esc_attr( $key ) . '"' . ( in_array( $key, $values, true ) ? ' selected' : '' ) . self::counted( $key, $label, $counts ) . '</option>';
		};
		$html   = '<select' . self::attrs( $attrs ) . '>';
		foreach ( $options as $key => $label ) {
			if ( is_array( $label ) ) {
				$html .= '<optgroup label="' . esc_attr( (string) $key ) . '">';
				foreach ( $label as $k => $l ) {
					$html .= $option( (string) $k, (string) $l );
				}
				$html .= '</optgroup>';
				continue;
			}
			$html .= $option( (string) $key, (string) $label );
		}
		return $html . '</select>';
	}

	/**
	 * A dialog on the chrome's recipe: a title, a body, a footer with Cancel and the confirming button; opened by
	 * any `[data-ra-dialog="<id>"]` control, closed by `[data-ra-dialog-close]` and the backdrop.
	 *
	 * @param string               $id    The element id.
	 * @param string               $title The title (raw).
	 * @param string               $body  The body (escaped HTML).
	 * @param array<string, mixed> $opts  confirm (the confirming button's label; '' for none), cancel (label),
	 *                                    variant (destructive: the confirming button in red), confirm_word (type
	 *                                    this word to enable the confirming button), form (the dialog is a form:
	 *                                    action, method), wide, class, attrs (on the confirming button); 0.55.0:
	 *                                    dialog_attrs, title_attrs, cancel_attrs (a product's hooks), footer (escaped
	 *                                    HTML in place of Cancel and the confirming button).
	 */
	public static function dialog( string $id, string $title, string $body, array $opts = array() ): string {
		$destructive = 'destructive' === ( $opts['variant'] ?? '' );
		$confirm     = (string) ( $opts['confirm'] ?? __( 'Confirm', 'ai-eshop-optimizer' ) );
		$word        = (string) ( $opts['confirm_word'] ?? '' );
		$form        = is_array( $opts['form'] ?? null );
		$hooks       = static fn( string $key ): string => self::attrs( is_array( $opts[ $key ] ?? null ) ? $opts[ $key ] : array() );
		$html        = '<dialog class="rooster-admin-dialog rooster-admin-dialog--kit' . ( ! empty( $opts['wide'] ) ? ' is-wide' : '' ) . ( $destructive ? ' is-destructive' : '' ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . esc_attr( (string) $opts['class'] ) : '' ) . '" id="' . esc_attr( $id ) . '" aria-labelledby="' . esc_attr( $id ) . '-title"' . $hooks( 'dialog_attrs' ) . '>'
			. ( $form ? '<form method="' . esc_attr( (string) ( $opts['form']['method'] ?? 'post' ) ) . '"' . ( '' !== (string) ( $opts['form']['action'] ?? '' ) ? ' action="' . esc_url( (string) $opts['form']['action'] ) . '"' : '' ) . '>' : '' )
			. '<div class="rooster-admin-dialog__header"><h2 id="' . esc_attr( $id ) . '-title"' . $hooks( 'title_attrs' ) . '>' . esc_html( $title ) . '</h2>'
			. '<button type="button" class="rooster-admin-dialog__x" data-ra-dialog-close="" aria-label="' . esc_attr__( 'Close', 'ai-eshop-optimizer' ) . '">' . Icons::ui( 'close', 16 ) . '</button></div>'
			. '<div class="rooster-admin-dialog__body">' . $body;
		if ( '' !== $word ) {
			$html .= '<p class="rooster-admin-dialog__confirmword"><label for="' . esc_attr( $id ) . '-word">' . sprintf(
				/* translators: %s: the word to type. */
				esc_html__( 'Type %s to confirm', 'ai-eshop-optimizer' ),
				'<code>' . esc_html( $word ) . '</code>'
			) . '</label><input type="text" class="rooster-admin-input" id="' . esc_attr( $id ) . '-word" data-ra-confirm-word="' . esc_attr( $word ) . '" autocomplete="off" /></p>';
		}
		$html .= '</div><div class="rooster-admin-dialog__footer">';
		if ( isset( $opts['footer'] ) ) {
			return $html . (string) $opts['footer'] . '</div>' . ( $form ? '</form>' : '' ) . '</dialog>';
		}
		$html .= self::button( (string) ( $opts['cancel'] ?? __( 'Cancel', 'ai-eshop-optimizer' ) ), array( 'attrs' => ( is_array( $opts['cancel_attrs'] ?? null ) ? $opts['cancel_attrs'] : array() ) + array( 'data-ra-dialog-close' => '' ) ) );
		if ( '' !== $confirm ) {
			$attrs = ( is_array( $opts['attrs'] ?? null ) ? $opts['attrs'] : array() ) + array( 'data-ra-dialog-confirm' => '' );
			if ( '' !== $word ) {
				$attrs['disabled'] = true;
			}
			$html .= self::button(
				$confirm,
				array(
					'variant' => $destructive ? 'destructive' : 'primary',
					'type'    => $form ? 'submit' : 'button',
					'attrs'   => $attrs,
				)
			);
		}
		return $html . '</div>' . ( $form ? '</form>' : '' ) . '</dialog>';
	}

	/**
	 * A picker: a dialog with a search, a checkable list (a tree when items have children: a product's variations,
	 * a category's branches), the count of the chosen in the footer, Cancel and Done. Opened by a
	 * `[data-ra-dialog="<id>"]` control; Done fills the `[data-ra-picker-summary="<id>"]` element beside the
	 * control with chips of the chosen (the e-shop Manager's "Choose brands", "Choose categories", "Choose products").
	 *
	 * @param string                           $id    The element id.
	 * @param string                           $title The title (raw).
	 * @param array<int, array<string, mixed>> $items {value, label (raw; " › " separates a path), count (int|null),
	 *                                                children (items), checked, note (raw, e.g. a SKU)}.
	 * @param array<string, mixed>             $opts  name (the checkboxes' name), search (placeholder), done, cancel,
	 *                                                empty (the summary's text when nothing is chosen), one, many
	 *                                                ("%s item selected", "%s items selected"), wide.
	 */
	public static function picker( string $id, string $title, array $items, array $opts = array() ): string {
		$name = (string) ( $opts['name'] ?? $id );
		/* translators: %s: the number of items picked. */
		$html = '<dialog class="rooster-admin-dialog rooster-admin-dialog--kit rooster-admin-picker' . ( ! empty( $opts['wide'] ) ? ' is-wide' : '' ) . '" id="' . esc_attr( $id ) . '" aria-labelledby="' . esc_attr( $id ) . '-title" data-ra-picker="" data-empty="' . esc_attr( (string) ( $opts['empty'] ?? __( 'Nothing picked', 'ai-eshop-optimizer' ) ) ) . '" data-one="' . esc_attr( (string) ( $opts['one'] ?? __( '%s item selected', 'ai-eshop-optimizer' ) ) ) . '" data-many="' . esc_attr( (string) ( $opts['many'] ?? __( '%s items selected', 'ai-eshop-optimizer' ) ) ) . '">'
			. '<div class="rooster-admin-dialog__header"><h2 id="' . esc_attr( $id ) . '-title">' . esc_html( $title ) . '</h2>'
			. '<button type="button" class="rooster-admin-dialog__x" data-ra-dialog-close="" aria-label="' . esc_attr__( 'Close', 'ai-eshop-optimizer' ) . '">' . Icons::ui( 'close', 16 ) . '</button></div>'
			. '<div class="rooster-admin-picker__search">' . self::input( $id . '-search', '', array( 'type' => 'search', 'icon' => 'search', 'placeholder' => (string) ( $opts['search'] ?? __( 'Search…', 'ai-eshop-optimizer' ) ), 'attrs' => array( 'data-ra-picker-search' => '', 'aria-label' => (string) ( $opts['search'] ?? __( 'Search', 'ai-eshop-optimizer' ) ) ) ) ) . '</div>'
			. '<div class="rooster-admin-dialog__body rooster-admin-picker__body">' . self::picker_list( $items, $name, $id ) . '</div>'
			/* translators: %s: the number of items picked. */
			. '<div class="rooster-admin-dialog__footer rooster-admin-picker__foot"><span class="rooster-admin-picker__selected" data-ra-picker-count="">' . esc_html( sprintf( (string) ( $opts['many'] ?? __( '%s items selected', 'ai-eshop-optimizer' ) ), '0' ) ) . '</span>'
			. self::button( (string) ( $opts['cancel'] ?? __( 'Cancel', 'ai-eshop-optimizer' ) ), array( 'attrs' => array( 'data-ra-dialog-close' => '' ) ) )
			. self::button( (string) ( $opts['done'] ?? __( 'Done', 'ai-eshop-optimizer' ) ), array( 'variant' => 'primary', 'attrs' => array( 'data-ra-dialog-confirm' => '' ) ) ) . '</div></dialog>';
		return $html;
	}

	/**
	 * The picker's list, one level.
	 *
	 * @param array<int, array<string, mixed>> $items Items.
	 * @param string                           $name  The checkboxes' name.
	 * @param string                           $id    The picker's id.
	 */
	private static function picker_list( array $items, string $name, string $id ): string {
		$html = '<ul class="rooster-admin-picker__list">';
		foreach ( $items as $i => $item ) {
			if ( ! is_array( $item ) || '' === (string) ( $item['label'] ?? '' ) ) {
				continue;
			}
			$children = is_array( $item['children'] ?? null ) ? $item['children'] : array();
			$path     = explode( ' › ', (string) $item['label'] );
			$label    = implode( '<span class="rooster-admin-picker__sep" aria-hidden="true">›</span>', array_map( 'esc_html', $path ) );
			$html    .= '<li class="rooster-admin-picker__item' . ( array() !== $children ? ' has-children' : '' ) . '"><div class="rooster-admin-picker__row">'
				. ( array() !== $children ? '<button type="button" class="rooster-admin-picker__toggle" aria-expanded="false" aria-label="' . esc_attr__( 'Show the variations', 'ai-eshop-optimizer' ) . '">' . Icons::ui( 'chevron', 14 ) . '</button>' : '' )
				. '<label class="rooster-admin-picker__check"><input type="checkbox" name="' . esc_attr( $name ) . '[]" value="' . esc_attr( (string) ( $item['value'] ?? $i ) ) . '"' . ( ! empty( $item['checked'] ) ? ' checked' : '' ) . ' data-label="' . esc_attr( end( $path ) ) . '" /><span class="rooster-admin-picker__label">' . $label
				. ( '' !== (string) ( $item['note'] ?? '' ) ? ' <span class="rooster-admin-picker__note">[' . esc_html( (string) $item['note'] ) . ']</span>' : '' )
				. ( isset( $item['count'] ) && null !== $item['count'] ? ' <span class="rooster-admin-picker__count">(' . esc_html( (string) $item['count'] ) . ')</span>' : '' ) . '</span></label>'
				/* translators: %s: how many variations. */
				. ( array() !== $children ? self::badge( sprintf( _n( '%s variation', '%s variations', count( $children ), 'ai-eshop-optimizer' ), number_format_i18n( count( $children ) ) ), 'info', array( 'sm' => true ) ) : '' )
				. '</div>' . ( array() !== $children ? '<div class="rooster-admin-picker__children" hidden>' . self::picker_list( $children, $name, $id ) . '</div>' : '' ) . '</li>';
		}
		return $html . '</ul>';
	}

	/**
	 * The toasts' region (printed once per screen by the chrome); the script adds toasts into it.
	 */
	public static function toast_region(): string {
		return '<div class="rooster-admin-toasts" id="rooster-admin-toasts" aria-live="polite" aria-atomic="false"></div>';
	}

	/**
	 * An empty state: an icon, a title, a sentence, an action.
	 *
	 * @param string               $title The title (raw).
	 * @param string               $text  The sentence (raw).
	 * @param array<string, mixed> $opts  icon (Lucide, default inbox), action (escaped HTML), compact.
	 */
	public static function empty_state( string $title, string $text = '', array $opts = array() ): string {
		return '<div class="rooster-admin-empty' . ( ! empty( $opts['compact'] ) ? ' is-compact' : '' ) . '">'
			. '<span class="rooster-admin-empty__icon" aria-hidden="true">' . Icons::svg( (string) ( $opts['icon'] ?? 'inbox' ), 28 ) . '</span>'
			. '<p class="rooster-admin-empty__title">' . esc_html( $title ) . '</p>'
			. ( '' !== $text ? '<p class="rooster-admin-empty__text">' . esc_html( $text ) . '</p>' : '' )
			. ( '' !== (string) ( $opts['action'] ?? '' ) ? '<div class="rooster-admin-empty__action">' . (string) $opts['action'] . '</div>' : '' ) . '</div>';
	}

	/**
	 * A pager: previous, the pages around the current one, next; the count beside it.
	 *
	 * @param int                  $page  The current page (1-based).
	 * @param int                  $pages The number of pages.
	 * @param string|callable      $base  The URL; `%d` is replaced by the page number (else `paged` is added); or a
	 *                                    callable given the page number (0.44.0).
	 * @param array<string, mixed> $opts  total (the item count), per_page, label (the nav's name).
	 */
	public static function pager( int $page, int $pages, $base, array $opts = array() ): string {
		$url  = static fn( int $n ): string => ! is_string( $base ) && is_callable( $base ) ? (string) $base( $n ) : Request::view_url( str_contains( (string) $base, '%d' ) ? sprintf( (string) $base, $n ) : add_query_arg( 'paged', $n, (string) $base ) );
		$page = max( 1, min( $page, max( 1, $pages ) ) );
		$html = '<nav class="rooster-admin-pager" aria-label="' . esc_attr( (string) ( $opts['label'] ?? __( 'Pages', 'ai-eshop-optimizer' ) ) ) . '">';
		if ( isset( $opts['total'] ) ) {
			/* translators: %s: the number of items. */
			$html .= '<span class="rooster-admin-pager__count">' . esc_html( sprintf( _n( '%s item', '%s items', (int) $opts['total'], 'ai-eshop-optimizer' ), number_format_i18n( (int) $opts['total'] ) ) ) . '</span>';
		}
		$html .= '<ul class="rooster-admin-pager__list">';
		$link  = static function ( int $n, string $label, bool $current = false, string $class = '', string $name = '' ) use ( $url ): string {
			// data-ra-page (0.49.0): the page, for a table that pages in the browser (table.js pager(), the same markup).
			return '<li><a class="rooster-admin-pager__link' . ( $current ? ' is-current' : '' ) . ( '' !== $class ? ' ' . $class : '' ) . '" href="' . esc_url( $url( $n ) ) . '" data-ra-page="' . (int) $n . '"' . ( '' !== $name ? ' aria-label="' . esc_attr( $name ) . '"' : '' ) . ( $current ? ' aria-current="page"' : '' ) . '>' . $label . '</a></li>';
		};
		if ( $page > 1 ) {
			$html .= $link( $page - 1, Icons::ui( 'chevron', 14 ) . '<span class="screen-reader-text">' . esc_html__( 'Previous page', 'ai-eshop-optimizer' ) . '</span>', false, 'is-prev' );
		}
		$window = array_unique( array_filter( array( 1, $page - 1, $page, $page + 1, $pages ), static fn( int $n ): bool => $n >= 1 && $n <= $pages ) );
		$last   = 0;
		foreach ( $window as $n ) {
			if ( $n - $last > 1 ) {
				$html .= '<li class="rooster-admin-pager__gap" aria-hidden="true">…</li>';
			}
			/* translators: %s: a page number. */
			$html .= $link( $n, esc_html( number_format_i18n( $n ) ), $n === $page, '', sprintf( __( 'Page %s', 'ai-eshop-optimizer' ), number_format_i18n( $n ) ) ); // each page link named (0.45.1)
			$last  = $n;
		}
		if ( $page < $pages ) {
			$html .= $link( $page + 1, '<span class="screen-reader-text">' . esc_html__( 'Next page', 'ai-eshop-optimizer' ) . '</span>' . Icons::ui( 'chevron', 14 ), false, 'is-next' );
		}
		return $html . '</ul></nav>';
	}

	/**
	 * A pager of named links only, no page numbers (0.44.0): previous and next, or first and more (a keyset), as the
	 * kit's pager links; a link without a URL is a disabled step.
	 *
	 * @param array<int, array<string, mixed>> $links {label (raw), url ('' for a disabled step), kind (prev, next:
	 *                                                 the chevron; first, more, or none), attrs}.
	 * @param array<string, mixed>             $opts  label (the nav's name).
	 */
	public static function pager_links( array $links, array $opts = array() ): string {
		$html = '<nav class="rooster-admin-pager" aria-label="' . esc_attr( (string) ( $opts['label'] ?? __( 'Pages', 'ai-eshop-optimizer' ) ) ) . '"><ul class="rooster-admin-pager__list">';
		foreach ( $links as $link ) {
			if ( ! is_array( $link ) ) {
				continue;
			}
			$kind  = (string) ( $link['kind'] ?? '' );
			$label = (string) ( $link['label'] ?? '' );
			$inner = 'prev' === $kind ? Icons::ui( 'chevron', 14 ) . '<span class="screen-reader-text">' . esc_html( $label ) . '</span>'
				: ( 'next' === $kind ? '<span class="screen-reader-text">' . esc_html( $label ) . '</span>' . Icons::ui( 'chevron', 14 ) : esc_html( $label ) );
			$attrs = array( 'class' => 'rooster-admin-pager__link' . ( '' !== $kind ? ' is-' . sanitize_html_class( $kind ) : '' ) ) + ( is_array( $link['attrs'] ?? null ) ? $link['attrs'] : array() );
			if ( '' === (string) ( $link['url'] ?? '' ) ) {
				$html .= '<li><span' . self::attrs( $attrs + array( 'aria-disabled' => 'true', 'aria-label' => $label ) ) . '>' . $inner . '</span></li>';
			} else {
				$html .= '<li><a' . self::attrs( $attrs + array( 'href' => (string) $link['url'], 'aria-label' => $label ) ) . '>' . $inner . '</a></li>';
			}
		}
		return $html . '</ul></nav>';
	}

	/**
	 * One record as label / value pairs (0.65.1, Rooster One's request 24; CONTRACT §8.2 "Facts"): a request's details,
	 * a message, a cache's state, shown as a box of facts, not a table of one row. A `<dl>` on the kit's key-value
	 * recipe: the labels aligned, a long value wrapping, a code selected whole by one click (to copy), an empty value a
	 * dash; on an admin screen without the chrome, in an island as a table is.
	 *
	 * @param array<int, array<string, mixed>> $facts {label (raw), value (raw; null or '' is a dash), html (escaped HTML in
	 *                                                place of the value), code (raw: a code, a key, a reference), tip
	 *                                                (raw: its toggletip after the label), tone (the value's: success,
	 *                                                destructive, warning, info, primary, mono)}.
	 * @param array<string, mixed>             $opts  columns (1, or 2: two pairs a row where the card is wide), class,
	 *                                                island (as Ui::table()'s).
	 */
	public static function facts( array $facts, array $opts = array() ): string {
		$items = array_values( array_filter( $facts, 'is_array' ) );
		$cols  = 2 === (int) ( $opts['columns'] ?? 1 ) ? 2 : 1;
		$count = count( $items );
		$last  = $count - ( 0 === $count % $cols ? $cols : $count % $cols ); // the first pair of the last row
		$html  = '';
		foreach ( $items as $i => $fact ) {
			$label = (string) ( $fact['label'] ?? '' );
			$tone  = '' !== (string) ( $fact['tone'] ?? '' ) ? 'is-tone-' . self::tone( (string) $fact['tone'] ) : '';
			$end   = $i >= $last ? 'is-last' : '';
			if ( isset( $fact['html'] ) ) {
				$value = (string) $fact['html'];
			} elseif ( '' !== (string) ( $fact['code'] ?? '' ) ) {
				$value = '<code class="rooster-admin-kv__code">' . esc_html( (string) $fact['code'] ) . '</code>';
			} elseif ( ! isset( $fact['value'] ) || '' === (string) $fact['value'] ) {
				$value = '<span class="rooster-admin-kv__none" aria-hidden="true">–</span><span class="screen-reader-text">' . esc_html__( 'None', 'ai-eshop-optimizer' ) . '</span>';
			} else {
				$value = esc_html( (string) $fact['value'] );
			}
			$tip   = '' !== (string) ( $fact['tip'] ?? '' ) ? ' ' . Guidance::tip( (string) $fact['tip'], $label ) : '';
			$html .= '<dt' . ( '' !== $end ? ' class="is-last"' : '' ) . '>' . esc_html( $label ) . $tip . '</dt><dd' . ( '' !== trim( $end . ' ' . $tone ) ? ' class="' . esc_attr( trim( $end . ' ' . $tone ) ) . '"' : '' ) . '>' . $value . '</dd>';
		}
		$dl = '<dl class="rooster-admin-kv' . ( 2 === $cols ? ' is-cols-2' : '' ) . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . esc_attr( (string) $opts['class'] ) : '' ) . '">' . $html . '</dl>';
		if ( ! empty( $opts['island'] ) || Library::off_chrome() ) {
			Library::island_style(); // the stylesheet alone: a box of facts runs no script
			return '<div class="rooster-admin rooster-admin-island">' . $dl . '</div>';
		}
		return $dl;
	}

	/**
	 * A column's figure (0.65.5, Rooster One's request 30): how its total is made and the format it is said in, for the
	 * first paint, a remote answer and the glue's recount (the totals cell's data-ra-figure); null for a plain sum of
	 * plain numbers. A column's `total`: 'sum' (the default), 'none', 'given' (0.65.6, request 36: the product's, in
	 * the column's format, never counted again: an average over every row of the set), or {ratio: [a, b] (the totals
	 * of two columns, a over b), percent (times 100, said with " %"), decimals}; its `format`: 'money' (the shop's currency, from
	 * WooCommerce: its symbol and position, decimals, separators; nothing where WooCommerce does not run) or {prefix,
	 * suffix, decimals, point, thousands} (the separators the site's language's by default).
	 *
	 * @param array<string, mixed> $col The column.
	 * @return array<string, mixed>|null
	 */
	private static function figure( array $col ): ?array {
		$total  = $col['total'] ?? 'sum';
		$format = $col['format'] ?? null;
		$fig    = array();
		$how    = 'given' === $total ? 'given' : 'sum';
		if ( 'none' === $total ) {
			return array( 'how' => 'none' );
		}
		if ( is_array( $total ) && is_array( $total['ratio'] ?? null ) && 2 === count( $total['ratio'] ) ) {
			$fig = array(
				'how'     => 'ratio',
				'of'      => array_values( array_map( 'strval', $total['ratio'] ) ),
				'percent' => ! empty( $total['percent'] ),
			);
			if ( isset( $total['decimals'] ) ) {
				$fig['decimals'] = (int) $total['decimals']; // else the format's, else 2
			}
			if ( $fig['percent'] ) {
				$fig['suffix'] = ' %';
			}
		}
		if ( 'money' === $format && function_exists( 'get_woocommerce_currency_symbol' ) ) {
			$symbol = html_entity_decode( (string) get_woocommerce_currency_symbol(), ENT_QUOTES, 'UTF-8' );
			$pos    = (string) get_option( 'woocommerce_currency_pos', 'left' );
			$fig   += array(
				'prefix'    => in_array( $pos, array( 'left', 'left_space' ), true ) ? $symbol . ( 'left_space' === $pos ? "\u{00a0}" : '' ) : '',
				'suffix'    => in_array( $pos, array( 'right', 'right_space' ), true ) ? ( 'right_space' === $pos ? "\u{00a0}" : '' ) . $symbol : '',
				'decimals'  => function_exists( 'wc_get_price_decimals' ) ? (int) wc_get_price_decimals() : 2,
				'point'     => function_exists( 'wc_get_price_decimal_separator' ) ? (string) wc_get_price_decimal_separator() : '',
				'thousands' => function_exists( 'wc_get_price_thousand_separator' ) ? (string) wc_get_price_thousand_separator() : '',
			);
		} elseif ( is_array( $format ) ) {
			$fig = array_merge(
				$fig,
				array_filter(
					array(
						'prefix'    => (string) ( $format['prefix'] ?? '' ),
						'suffix'    => (string) ( $format['suffix'] ?? ( $fig['suffix'] ?? '' ) ),
						'decimals'  => isset( $format['decimals'] ) ? (int) $format['decimals'] : null,
						'point'     => (string) ( $format['point'] ?? '' ),
						'thousands' => (string) ( $format['thousands'] ?? '' ),
					),
					static fn( $v ): bool => null !== $v && '' !== $v
				)
			);
		}
		$bands = self::bands( $col );
		if ( array() !== $bands ) {
			$fig['bands'] = $bands; // 0.65.7: the recount's tone
		}
		return array() === $fig && 'sum' === $how ? null : $fig + array( 'how' => $how );
	}

	/**
	 * A number in a figure's format (0.65.5): the prefix, the number with its decimals and separators (the site's
	 * language's unless the figure names them), the suffix; escaped.
	 *
	 * @param float                $n   The number.
	 * @param array<string, mixed> $fig figure()'s.
	 * @param int                  $d   The decimals, when the figure names none.
	 */
	private static function figure_text( float $n, array $fig, int $d ): string {
		$d    = isset( $fig['decimals'] ) ? (int) $fig['decimals'] : $d;
		$text = '' !== (string) ( $fig['point'] ?? '' ) ? number_format( $n, $d, (string) $fig['point'], (string) ( $fig['thousands'] ?? '' ) ) : number_format_i18n( $n, $d );
		return esc_html( (string) ( $fig['prefix'] ?? '' ) . $text . (string) ( $fig['suffix'] ?? '' ) );
	}

	/**
	 * A column's total as printed (escaped): the product's value in the column's format, or its HTML as given; a ratio
	 * column without one made from its two columns' totals (0.65.5).
	 *
	 * @param array<string, mixed> $col    The column.
	 * @param array<string, mixed> $totals key => int|float|string|{html}.
	 */
	private static function total_html( array $col, array $totals ): string {
		return self::total_cell( $col, $totals )['html'];
	}

	/**
	 * A column's total as printed and its band's tone (0.65.7): total_html()'s, with the band of its number (a ratio
	 * made from its two totals too) and the band's words after it for a screen reader.
	 *
	 * @param array<string, mixed> $col    The column.
	 * @param array<string, mixed> $totals key => int|float|string|{html}.
	 * @return array{html: string, tone: string}
	 */
	private static function total_cell( array $col, array $totals ): array {
		$key = (string) ( $col['key'] ?? '' );
		$fig = self::figure( $col );
		$n   = null;
		if ( null !== $fig && 'none' === $fig['how'] ) {
			return array(
				'html' => '',
				'tone' => '',
			);
		}
		$html = '';
		if ( array_key_exists( $key, $totals ) ) {
			$value = $totals[ $key ];
			$n     = is_int( $value ) || is_float( $value ) ? (float) $value : null;
			$html  = null !== $fig && null !== $n ? self::figure_text( $n, $fig, is_int( $value ) ? 0 : (int) ( $col['decimals'] ?? 2 ) ) : Guidance::total( $value, (int) ( $col['decimals'] ?? 2 ) );
		} elseif ( null !== $fig && 'ratio' === $fig['how'] ) {
			$a = $totals[ $fig['of'][0] ] ?? null;
			$b = $totals[ $fig['of'][1] ] ?? null;
			if ( is_numeric( $a ) && is_numeric( $b ) && 0.0 !== (float) $b ) {
				$n    = (float) $a / (float) $b * ( $fig['percent'] ? 100 : 1 );
				$html = self::figure_text( $n, $fig, 2 );
			}
		}
		$hit = null !== $n && '' !== $html ? self::band( $n, self::bands( $col ) ) : null;
		return array(
			'html' => $html . ( null !== $hit && '' !== $hit['label'] ? '<span class="screen-reader-text">, ' . esc_html( $hit['label'] ) . '</span>' : '' ),
			'tone' => null !== $hit ? $hit['tone'] : '',
		);
	}

	/**
	 * A column's tone bands (0.65.7, Rooster One's request 34): `bands` => [{below, tone, label}, …], in order, the
	 * thresholds in the column's own value; a value takes the first band it lies below, else the first without a
	 * `below` (the rest); a value no band takes has none. Each band's tone (a Ui tone, 'danger' is 'destructive'; ''
	 * none) and its words (raw: said after the value for a screen reader, the tone being more than a colour; the
	 * column's `tip` says the thresholds).
	 *
	 * @param array<string, mixed> $col The column.
	 * @return array<int, array{below?: float, tone: string, label: string}>
	 */
	private static function bands( array $col ): array {
		$out = array();
		foreach ( is_array( $col['bands'] ?? null ) ? $col['bands'] : array() as $band ) {
			if ( ! is_array( $band ) ) {
				continue;
			}
			$tone = 'danger' === ( $band['tone'] ?? '' ) ? 'destructive' : (string) ( $band['tone'] ?? '' );
			$one  = array(
				'tone'  => '' === $tone ? '' : self::tone( $tone ),
				'label' => (string) ( $band['label'] ?? '' ),
			);
			if ( is_numeric( $band['below'] ?? null ) ) {
				$out[] = array( 'below' => (float) $band['below'] ) + $one;
				continue;
			}
			$out[] = $one;
			break; // the rest: a band after it is never reached
		}
		return $out;
	}

	/**
	 * A value's band: the first it lies below, else the first without a `below`; null when none fits.
	 *
	 * @param float                            $n     The value.
	 * @param array<int, array<string, mixed>> $bands bands()'s.
	 * @return array<string, mixed>|null
	 */
	private static function band( float $n, array $bands ): ?array {
		foreach ( $bands as $band ) {
			if ( ! isset( $band['below'] ) || $n < $band['below'] ) {
				return $band;
			}
		}
		return null;
	}

	/**
	 * A cell's value for its column's bands: the row's sort value for the column (`_attrs['data-ra-s']`), else the
	 * cell's own number (a number, or an array's `value`).
	 *
	 * @param array<string, mixed> $row  The row.
	 * @param string               $key  The column's key.
	 * @param mixed                $cell The cell.
	 */
	private static function band_value( array $row, string $key, $cell ): ?float {
		$sort = $row['_attrs']['data-ra-s'] ?? null;
		$sort = is_string( $sort ) ? json_decode( $sort, true ) : $sort;
		if ( is_array( $sort ) && is_numeric( $sort[ $key ] ?? null ) ) {
			return (float) $sort[ $key ];
		}
		if ( is_int( $cell ) || is_float( $cell ) || ( is_string( $cell ) && is_numeric( $cell ) ) ) {
			return (float) $cell;
		}
		return is_array( $cell ) && is_numeric( $cell['value'] ?? null ) ? (float) $cell['value'] : null;
	}

	/**
	 * The table skin: a toolbar (search, filters, bulk actions), the head with sortable columns, typed cells, row
	 * actions, selection, and the footer (a pager). The engine (sorting, paging) is the product's; this is the look.
	 *
	 * @param array<int, array<string, mixed>>    $columns {key, label, type (text, num, date, status, progress,
	 *                                                     check, actions, html; 0.62.0: boolean, code; 0.62.1:
	 *                                                     image, with size sm 32, md 40 (the default), lg 56 or
	 *                                                     xl 80 px, alt (the row key of its alt text; none: a
	 *                                                     decorative image), and what a click does: link (the row
	 *                                                     key of its URL), preview (true: the larger image in a
	 *                                                     dialog) or action ({label, attrs}: a button with the
	 *                                                     product's hooks, data-ra-dialog among them)), sort ('',
	 *                                                     'asc', 'desc': the
	 *                                                     current order; the key carries `sort_url`; 0.62.0: the
	 *                                                     link carries data-ra-sort and its type, sort_type number,
	 *                                                     date or text, by default the column's), width (a
	 *                                                     CSS width keyword: 'min' for shrink-to-content; 0.63.1: xs
	 *                                                     6rem, sm 10rem, md 16rem, lg 24rem), align (0.63.1: start,
	 *                                                     center, end: over the type's own); 0.61.0:
	 *                                                     always (the Columns chooser never hides it), decimals (a
	 *                                                     float total's); 0.71.0 (TABLES-PLAN 1b): priority ('low':
	 *                                                     the column may go on a narrow table: the frame says its
	 *                                                     place in data-ra-drop, table.js hides it by the chooser's
	 *                                                     mechanics under 40 rem of the frame's width, the chooser
	 *                                                     lists it as hidden; never the first or an always
	 *                                                     column); 0.72.0 (1c): group (a heading over the run of
	 *                                                     columns that share it, the first row of the head, scope
	 *                                                     colgroup; never the first column, a grid's row label)}.
	 *                                                     An `actions` column (FR17) is the last; its
	 *                                                     cell may be a list of items, Guidance::row_buttons()'s,
	 *                                                     each button named with the row (`_name`, else the first
	 *                                                     cell's title).
	 * @param array<int, array<string, mixed>>    $rows    key => value per column; `_actions` (escaped HTML of row
	 *                                                     actions: Ui::row_actions()'s links), `_id`, `_selected`,
	 *                                                     `_tone` (a row tone), `_name` (raw: the row's name for its
	 *                                                     buttons; 0.61.0), `_attrs` (0.61.2: the row's own data-*
	 *                                                     attributes, raw values, a list or a map as JSON: the
	 *                                                     engine's data-ra-f, data-ra-s, data-ra-text, a product's
	 *                                                     own). A cell's array takes `tone` (0.62.0: the cell's own
	 *                                                     tone, a loss red; a status cell's tone is its badge's) and
	 *                                                     `tip` (0.63.1, raw: R4's toggletip after the value, named
	 *                                                     "About <column> of <row>"). 0.64.0: `_detail` (escaped
	 *                                                     HTML: the row's details, with the table's `details`); a
	 *                                                     `radio` column's cell {name, value, checked, label}: one
	 *                                                     choice per group (the duplicates a person keeps). 0.65.0,
	 *                                                     with `move`: `_locked` (raw: why the row keeps its place: a
	 *                                                     lock in its grip's place says so), `_zone` (it moves among
	 *                                                     its zone's rows only). 0.65.2: `_span` (escaped HTML: a row
	 *                                                     across the table in place of its cells, a note; `_span_kind`
	 *                                                     'label' for a section label; the engine keeps it with the
	 *                                                     row above it, as a details row); a cell's array takes
	 *                                                     `colspan` (the columns it covers print nothing in that row).
	 * @param array<string, mixed>                $opts    id, caption (raw), striped, dense, selectable, toolbar
	 *                                                     (escaped HTML), bulk (escaped HTML), footer (escaped
	 *                                                     HTML), empty (escaped HTML for no rows), sticky; 0.61.0
	 *                                                     (CONTRACT §8.5): sticky_first (the first column stays while
	 *                                                     the rest scrolls), scroll (the scroll region focusable and
	 *                                                     named: true, or its name; implied by sticky_first and
	 *                                                     chooser), chooser (needs id: true, or {shown: the product's
	 *                                                     default set of keys}: the Columns chooser, the person's
	 *                                                     choice kept), export (Guidance::export()'s options: the
	 *                                                     CSV and XLSX pair; 0.76.0: columns 'visible', the files
	 *                                                     follow the Columns choice; views 'sheets', the XLSX holds
	 *                                                     every view, one sheet each; the table's prefix and the
	 *                                                     keys shown passed on: CONTRACT §8.5 "The export"), totals
	 *                                                     (key => int|float|string|{html}: the totals row),
	 *                                                     totals_label (raw; "Total");
	 *                                                     rows_template (0.61.2, §8.2: the list for the local engine
	 *                                                     in a `<template data-ra-rows>` inside the table: true, the
	 *                                                     rows shown; or every row of the list, the rows shown being
	 *                                                     the first paint); local (0.62.0, §8.2: the library wires
	 *                                                     the table in the browser, roosterAdminTable.local(): true,
	 *                                                     or {size (rows a page; 0 every row), sizes (0.65.3: the
	 *                                                     choices of rows a page, a select in the footer before the
	 *                                                     pager; size defaults to the first), asked (0.69.0: the
	 *                                                     rows a page the product read from the address itself, a
	 *                                                     public page's table), words (every word of
	 *                                                     the search, in any order), tie, sort (the default order:
	 *                                                     {key, dir}), paged, keys (the address's names: s, orderby,
	 *                                                     order, paged), label (the pager's name), none (escaped
	 *                                                     HTML: the no-results state), form (0.64.2: a grid posted
	 *                                                     as one form, its rows the page's own, sorted, filtered and
	 *                                                     paged in place, so every row's inputs post with the form)};
	 *                                                     implies rows_template, but for a form grid);
	 *                                                     filters (0.64.0: the declared filters, Filters: the bar
	 *                                                     at the toolbar's start, the active ones as chips under it,
	 *                                                     their kinds for the engine and the remote request), search
	 *                                                     (0.64.0: true or {label, placeholder}: the bar's search
	 *                                                     box), filter_values (the values, when the product read them
	 *                                                     already: Filters::values(); a public page's table passes
	 *                                                     them, the library reads the address only in wp-admin, with
	 *                                                     the view nonce), typed (0.69.0: the search the product
	 *                                                     read), details (0.64.0: each row's
	 *                                                     `_detail`, escaped HTML, in a full-width row under it,
	 *                                                     opened by its Details button);
	 *                                                     capped (0.63.1: {shown, total, text}: a list cut at its
	 *                                                     first rows says so under the table, "Showing the first
	 *                                                     500 of 12,340 rows"; 0.65.2: without a total, "Showing
	 *                                                     the first 500 rows"); choices (0.62.1: id => value => label,
	 *                                                     the shared lists
	 *                                                     of its editable select cells, Ui::choices()); 0.63.0
	 *                                                     (§8.2): remote (the rows a page at a time from the
	 *                                                     product's route, Ui::answer(): {url, nonce, scope (the
	 *                                                     fixed parameters: the report, the branch), context
	 *                                                     (admin or storefront: said, never inferred), options (the
	 *                                                     route of the filters' choices), size, sizes (the rows a
	 *                                                     page offered), total, paged, sort, keys, prefix, label}),
	 *                                                     edit (its editable cells saved through the product's route
	 *                                                     with no script of its own: {url, nonce, open}); local and
	 *                                                     remote take prefix (every name in the address, filters
	 *                                                     included: several tables on one screen). 0.65.0: move (rows
	 *                                                     that move, each by its grip: true, the order event only; or
	 *                                                     {name (each row's hidden `<name>[]`, its key: the order
	 *                                                     posts with the form), save ({url, nonce}: each move sent
	 *                                                     at once, with Undo), default (the keys in their default
	 *                                                     order: Reset to default), label (raw: the list's name)};
	 *                                                     every row needs its `_id`; not a remote table's). 0.65.1:
	 *                                                     island (true: the table in its own token scope with its
	 *                                                     assets, for an admin screen without the chrome; on such a
	 *                                                     screen it is on its own, and in an AJAX answer meant for
	 *                                                     one it is asked for). 0.73.0 (TABLES-PLAN 1d): cards (true:
	 *                                                     a list of records becomes a card per row under 40 rem of
	 *                                                     the frame; each cell carries its column's name, the head
	 *                                                     is a row of the sort links; its own stylesheet, loaded by
	 *                                                     the table). 0.74.4: attrs (the frame's own data-*
	 *                                                     attributes, a product's hooks on the table, raw values,
	 *                                                     a list or a map as JSON: as a row's `_attrs`; Rooster
	 *                                                     One's adapter wrapped the table for its table_data).
	 */
	public static function table( array $columns, array $rows, array $opts = array() ): string {
		$id      = (string) ( $opts['id'] ?? '' );
		$columns = array_values( $columns );
		$select  = ! empty( $opts['selectable'] );
		$move    = self::move_conf( $opts['move'] ?? null ); // 0.65.0: rows that move
		$lead    = ( null !== $move ? 1 : 0 ) + ( $select ? 1 : 0 ) + ( ! empty( $opts['details'] ) ? 1 : 0 ); // the cells before the first column's
		$chooser = $opts['chooser'] ?? null;
		$choose  = '' !== $id && ( true === $chooser || is_array( $chooser ) );
		$hide    = '';
		$hidden  = array(); // 0.72.0: the places hidden now, keyed, for the group row's spans
		$aside   = '';
		$picker  = '';
		$visible = array(); // 0.76.0: the keys shown now, when the chooser hides some (an export that follows them)
		if ( $choose ) { // the Columns chooser (0.61.0): the cells of a hidden column are hidden by their place in the row
			$default = is_array( $chooser ) && is_array( $chooser['shown'] ?? null ) ? $chooser['shown'] : null;
			$shown   = Guidance::shown( $id, $columns, $default );
			foreach ( $columns as $i => $col ) {
				$place = $i + 1 + $lead;
				if ( $i > 0 && empty( $col['always'] ) && $place <= Guidance::HIDE_MAX && ! in_array( (string) ( $col['key'] ?? '' ), $shown, true ) ) {
					$hide            .= ' is-hide-' . $place;
					$hidden[ $place ] = true;
				} else {
					$visible[] = (string) ( $col['key'] ?? '' );
				}
			}
			$picker = Guidance::columns(
				$id,
				$columns,
				array(
					'shown'   => $shown,
					'default' => null === $default ? array_column( $columns, 'key' ) : $default,
					'offset'  => $lead,
				)
			);
		}
		if ( is_array( $opts['export'] ?? null ) ) { // the export pair, then the chooser, at the toolbar's end
			// 0.76.0: the pair's options name their parameters under the table's prefix (a remote table's, else a local
			// one's), and an export that follows the Columns choice carries the keys shown now from the first paint.
			$conf   = is_array( $opts['remote'] ?? null ) && '' !== (string) ( $opts['remote']['url'] ?? '' ) ? $opts['remote'] : ( is_array( $opts['local'] ?? null ) ? $opts['local'] : array() );
			$aside .= Guidance::export( $opts['export'] + array( 'prefix' => (string) ( $conf['prefix'] ?? '' ) ) + ( $choose && count( $visible ) < count( $columns ) ? array( 'shown' => $visible ) : array() ) );
		}
		$aside .= $picker;
		$drop   = array(); // 0.71.0 (TABLES-PLAN 1b): the columns that may go on a narrow table, by their place (the chooser's places), for table.js
		foreach ( $columns as $i => $col ) {
			$place = $i + 1 + $lead;
			if ( $i > 0 && 'low' === (string) ( $col['priority'] ?? '' ) && empty( $col['always'] ) && $place <= Guidance::HIDE_MAX ) {
				$drop[] = $place;
			}
		}
		$scale  = '' !== $id && ! empty( $opts['text_size'] ) ? self::text_size( $id ) : 0; // 0.68.0: a busy table's text size
		$scaler = $scale > 0 ? '<div class="rooster-admin-table__scale">' . self::text_size_button( $id ) . '</div>' : ''; // first on the toolbar's right (the owner)
		$stick  = ! empty( $opts['sticky_first'] );
		$cards  = ! empty( $opts['cards'] ); // 0.73.0 (TABLES-PLAN 1d): a card per row under 40 rem, its own stylesheet
		$region = $opts['scroll'] ?? ( $stick || $choose );
		$far    = is_array( $opts['remote'] ?? null ) && '' !== (string) ( $opts['remote']['url'] ?? '' ); // 0.63.0: a page at a time
		if ( $far ) {
			$opts['local'] = $opts['remote'];
			unset( $opts['rows_template'] );
		}
		$live = true === ( $opts['local'] ?? null ) || is_array( $opts['local'] ?? null );
		$grid = $live && is_array( $opts['local'] ?? null ) && ! empty( $opts['local']['form'] ) && ! $far; // 0.64.2: a grid posted as one form, worked in place
		$decl = is_array( $opts['filters'] ?? null ) ? $opts['filters'] : array(); // 0.64.0: the declared filters
		$pre  = is_array( $opts['local'] ?? null ) ? preg_replace( '/[^A-Za-z0-9_-]/', '', (string) ( $opts['local']['prefix'] ?? '' ) ) : '';
		$fval = array();
		if ( array() !== $decl ) {
			$fval  = is_array( $opts['filter_values'] ?? null ) ? $opts['filter_values'] : Filters::values( $decl, $pre );
			$skey  = is_array( $opts['local'] ?? null ) && '' !== (string) ( $opts['local']['keys']['s'] ?? '' ) ? (string) $opts['local']['keys']['s'] : $pre . 's';
			$typed = isset( $opts['typed'] ) ? (string) $opts['typed'] : (string) Request::text( $skey ); // a view's search (0.69.0: the product's own reading, `typed`, first)
			$opts['toolbar'] = Filters::bar(
				'' !== $id ? $id : 'rooster-admin-table',
				$decl,
				$fval,
				array(
					'prefix'  => $pre,
					'search'  => $opts['search'] ?? false,
					'typed'   => $typed,
					'keys'     => array( 's' => $skey ),
					'caption'  => (string) ( $opts['caption'] ?? '' ),
					'detached' => $grid, // inside the grid's own form: no form of its own, its controls never posted
				)
			) . (string) ( $opts['toolbar'] ?? '' );
		}
		$details = ! empty( $opts['details'] );
		if ( $live && ! $far && ! $grid && ! isset( $opts['rows_template'] ) ) {
			$opts['rows_template'] = true;
		}
		if ( $live ) {
			wp_enqueue_script( 'rooster-admin-table-local' ); // its glue, on the screens that print a local table only
		}
		if ( $cards ) {
			wp_enqueue_style( 'rooster-admin-table-cards' ); // 0.73.0: its stylesheet, on the screens that print a list as cards only
		}
		// 0.65.3: the rows a page, chosen (`sizes`, Rooster One's request 27): a nameless select the glue reads, in the
		// footer before its pager; the address's choice (the table's prefix), else `size`, else the first of `sizes`.
		$sizer = '';
		$lconf = is_array( $opts['local'] ?? null ) ? $opts['local'] : array();
		$sizes = array_values( array_unique( array_filter( array_map( 'intval', (array) ( $lconf['sizes'] ?? array() ) ), static fn( int $n ): bool => $n > 0 ) ) );
		if ( $live && count( $sizes ) > 1 && false === strpos( (string) ( $opts['toolbar'] ?? '' ), 'data-ra-size' ) ) {
			$pkey  = '' !== (string) ( $lconf['keys']['per_page'] ?? '' ) ? (string) $lconf['keys']['per_page'] : $pre . 'per_page';
			$asked = isset( $lconf['asked'] ) ? (int) $lconf['asked'] : Request::number( $pkey ); // a view's rows a page (0.69.0: the product's own reading, `asked`, first)
			$given = (int) ( $lconf['size'] ?? 0 );
			$size  = in_array( $asked, $sizes, true ) ? $asked : ( $given > 0 ? $given : $sizes[0] );
			$sid   = ( '' !== $id ? $id : 'rooster-admin-table' ) . '-size';
			$sizer = '<span class="rooster-admin-table__size"><label for="' . esc_attr( $sid ) . '">' . esc_html__( 'Rows a page', 'ai-eshop-optimizer' ) . '</label>'
				. self::select(
					'',
					array_combine( array_map( 'strval', $sizes ), array_map( 'number_format_i18n', $sizes ) ),
					(string) $size,
					array(
						'id'    => $sid,
						'xs'    => true,
						'attrs' => array( 'data-ra-size' => '' ),
					)
				) . '</span>';
		}
		// 0.65.1: a table on an admin screen without the chrome (a WooCommerce order, a post's editor) brings its own
		// assets and sits in an island, where the kit's tokens apply as on a chrome screen.
		$island = ! empty( $opts['island'] ) || Library::off_chrome();
		if ( $island ) {
			Library::table_assets( array_keys( array_filter( array( 'local' => $live, 'move' => null !== $move, 'cards' => $cards ) ) ) );
		}
		$name   = is_string( $region ) && '' !== $region ? $region : (string) ( $opts['caption'] ?? '' );
		$html   = '<div class="rooster-admin-table' . ( ! empty( $opts['striped'] ) ? ' is-striped' : '' ) . ( ! empty( $opts['dense'] ) ? ' is-dense' : '' ) . ( ! empty( $opts['sticky'] ) ? ' is-sticky' : '' ) . ( $stick ? ' is-sticky-first' : '' ) . ( $cards ? ' is-cards' : '' ) . $hide . '"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '"' : '' ) . ( array() !== $drop ? ' data-ra-drop="' . esc_attr( implode( ',', $drop ) ) . '"' : '' ) . ( $scale > 0 ? ' data-ra-text-size="' . $scale . '"' : '' ) . ( $live ? ' data-ra-local="' . esc_attr( (string) wp_json_encode( self::local_config( is_array( $opts['local'] ) ? $opts['local'] : array(), $far, $decl, (string) ( $opts['caption'] ?? '' ) ) ) ) . '"' : '' ) . self::edit_attrs( $opts['edit'] ?? null ) . self::move_attrs( $move, '' !== $id ? $id : 'rooster-admin-table' ) . self::row_attrs( $opts['attrs'] ?? null ) . '>'; // 0.74.4: the frame's own data-* attributes (a product's hooks), as a row's _attrs
		if ( '' !== (string) ( $opts['toolbar'] ?? '' ) || '' !== (string) ( $opts['bulk'] ?? '' ) || '' !== $aside || '' !== $scaler ) {
			$html .= '<div class="rooster-admin-table__toolbar">' . (string) ( $opts['toolbar'] ?? '' ) . $scaler . ( '' !== (string) ( $opts['bulk'] ?? '' ) ? '<div class="rooster-admin-table__bulk">' . (string) $opts['bulk'] . '</div>' : '' )
				. ( '' !== $aside ? '<div class="rooster-admin-table__aside">' . $aside . '</div>' : '' ) . '</div>';
		}
		if ( array() !== $decl ) { // the active filters as chips, Clear filters (0.64.0); the glue redraws them after each view
			/* translators: the row of chips that shows the active filters. */
			$html .= '<div class="rooster-admin-table__chips" data-ra-chips="" role="group" aria-label="' . esc_attr__( 'Active filters', 'ai-eshop-optimizer' ) . '">' . Filters::chips( $decl, $fval, $pre ) . '</div>';
		}
		// A wide table's scroll region takes the keyboard's focus and has a name (FR17; axe's scrollable-region-focusable):
		// printed here when declared, added by table.js to any other region while it overflows.
		$scroll = $region ? ' tabindex="0" role="region" aria-label="' . esc_attr( '' !== $name ? $name : __( 'Table', 'ai-eshop-optimizer' ) ) . '" data-ra-region=""' : '';
		$html  .= '<div class="rooster-admin-table__scroll"' . $scroll . '><table class="rooster-admin-table__table">' . ( '' !== (string) ( $opts['caption'] ?? '' ) ? '<caption class="screen-reader-text">' . esc_html( (string) $opts['caption'] ) . '</caption>' : '' ) . '<thead>' . self::group_row( $columns, array( 'move' => null !== $move, 'check' => $select, 'detail' => $details ), $hidden, $stick ) . '<tr' . ( $cards && self::sorts( $columns ) ? ' data-ra-sort-label="' . esc_attr__( 'Sort by', 'ai-eshop-optimizer' ) . '"' : '' ) . '>'; // 0.73.0: as cards, the head is a row of the sort links after "Sort by"
		if ( null !== $move ) { // 0.65.0: the column of the rows' grips
			$html .= '<th class="rooster-admin-table__th is-move" scope="col"><span class="screen-reader-text">' . esc_html__( 'Order', 'ai-eshop-optimizer' ) . '</span></th>';
		}
		if ( ! empty( $opts['selectable'] ) ) {
			$html .= '<th class="rooster-admin-table__th is-check" scope="col"><input type="checkbox" aria-label="' . esc_attr__( 'Select all', 'ai-eshop-optimizer' ) . '" data-ra-select-all="" /></th>';
		}
		if ( $details ) { // 0.64.0: the column of the Details buttons
			$html .= '<th class="rooster-admin-table__th is-detail" scope="col"><span class="screen-reader-text">' . esc_html__( 'Details', 'ai-eshop-optimizer' ) . '</span></th>';
		}
		foreach ( $columns as $i => $col ) {
			$type  = (string) ( $col['type'] ?? 'text' );
			$sort  = (string) ( $col['sort'] ?? '' );
			$html .= '<th class="rooster-admin-table__th is-' . esc_attr( $type ) . ( $stick && 0 === $i ? ' is-first' : '' ) . self::col_classes( $col ) . '" scope="col"' . ( '' !== $sort && 'none' !== $sort ? ' aria-sort="' . ( 'asc' === $sort ? 'ascending' : 'descending' ) . '"' : '' ) . '>';
			if ( isset( $col['sort'] ) && '' !== (string) ( $col['sort_url'] ?? '' ) ) {
				$html .= '<a class="rooster-admin-table__sort' . ( '' !== $sort && 'none' !== $sort ? ' is-on' : '' ) . '" href="' . esc_url( (string) $col['sort_url'] ) . '" data-ra-sort="' . esc_attr( (string) ( $col['key'] ?? '' ) ) . '" data-ra-sort-type="' . esc_attr( self::sort_type( $col ) ) . '">' . esc_html( (string) $col['label'] ) . Icons::ui( 'caret', 12 ) . '</a>';
			} elseif ( 'actions' === $type ) { // 0.80.2 (the owner, 6 Nov 2026): said, not shown; the buttons name themselves, the column keeps its content's width
				$html .= '<span class="screen-reader-text">' . esc_html( '' !== (string) ( $col['label'] ?? '' ) ? (string) $col['label'] : __( 'Actions', 'ai-eshop-optimizer' ) ) . '</span>';
			} else {
				$html .= esc_html( (string) $col['label'] );
			}
			$html .= ( '' !== (string) ( $col['tip'] ?? '' ) ? ' ' . Guidance::tip( (string) $col['tip'], (string) ( $col['label'] ?? '' ) ) : '' ) . '</th>'; // 0.65.5: R4's toggletip, "About <column>"
		}
		$html .= '</tr></thead><tbody>';
		if ( array() === $rows ) {
			// Its content held in view on a wide table (0.68.24, table.js's --ra-view): a cell that spans every column centred
			// its words on the whole table, off to the right of what was on screen.
			$html .= '<tr><td class="rooster-admin-table__empty" colspan="' . ( count( $columns ) + $lead ) . '"><div class="rooster-admin-table__empty-in">' . ( '' !== (string) ( $opts['empty'] ?? '' ) ? (string) $opts['empty'] : esc_html__( 'Nothing here yet.', 'ai-eshop-optimizer' ) ) . '</div></td></tr>';
		}
		$html .= self::table_rows( $columns, $rows, $select, $details, $move, $cards );
		$html .= '</tbody>';
		if ( is_array( $opts['totals'] ?? null ) && array() !== $columns ) { // the totals row (0.61.0): each cell named by its key, for an engine that recounts
			if ( $live ) {
				wp_enqueue_script( 'rooster-admin-table-totals' ); // 0.65.7: its script, with a live totals row only
			}
			$totals = $opts['totals'];
			$html  .= '<tfoot><tr class="rooster-admin-table__row is-total">' . ( null !== $move ? '<td class="rooster-admin-table__td is-move"></td>' : '' ) . ( $select ? '<td class="rooster-admin-table__td is-check"></td>' : '' ) . ( $details ? '<td class="rooster-admin-table__td is-detail"></td>' : '' );
			foreach ( $columns as $i => $col ) {
				$key   = (string) ( $col['key'] ?? '' );
				$type  = esc_attr( (string) ( $col['type'] ?? 'text' ) );
				$cell  = self::total_cell( $col, $totals );
				$value = $cell['html'];
				$fig   = $live ? self::figure( $col ) : null; // 0.65.5: how table-totals.js makes it again, in the column's format
				$html .= 0 === $i
					? '<th class="rooster-admin-table__td is-' . $type . ' is-first" scope="row">' . ( '' !== $value ? $value : esc_html( (string) ( $opts['totals_label'] ?? __( 'Total', 'ai-eshop-optimizer' ) ) ) ) . '</th>'
					: '<td class="rooster-admin-table__td is-' . $type . ( '' !== $cell['tone'] ? ' is-tone-' . $cell['tone'] : '' ) . '"' . ( $cards && 'actions' !== $type ? ' data-ra-label="' . esc_attr( (string) ( $col['label'] ?? '' ) ) . '"' : '' ) . ' data-ra-total="' . esc_attr( $key ) . '"' . ( $live ? ' data-ra-decimals="' . (int) ( $col['decimals'] ?? 2 ) . '"' : '' ) . ( null !== $fig ? ' data-ra-figure="' . esc_attr( (string) wp_json_encode( $fig ) ) . '"' : '' ) . '>' . $value . '</td>';
			}
			$html .= '</tr></tfoot>';
		}
		$html .= '</table></div>';
		$after = '';
		if ( null !== $move ) {
			[ $foot, $after ] = self::move_foot( $move, '' !== $id ? $id : 'rooster-admin-table', (string) ( $opts['caption'] ?? '' ) );
			$html            .= $foot;
		}
		$capped = is_array( $opts['capped'] ?? null ) ? $opts['capped'] : null;
		$whole  = null !== $capped && (int) ( $capped['total'] ?? 0 ) > 0; // 0.65.2: a list cut without knowing how long it is
		if ( null !== $capped && ( $whole ? (int) $capped['total'] > (int) ( $capped['shown'] ?? 0 ) : (int) ( $capped['shown'] ?? 0 ) > 0 ) ) { // a list cut at its first rows says so (0.63.1)
			$words = '' !== (string) ( $capped['text'] ?? '' ) ? (string) $capped['text'] : ( $whole ? sprintf(
				/* translators: 1: the rows shown, 2: every row. */
				__( 'Showing the first %1$s of %2$s rows. Narrow the search or the filters to see the others.', 'ai-eshop-optimizer' ),
				number_format_i18n( (int) $capped['shown'] ),
				number_format_i18n( (int) $capped['total'] )
			) : sprintf(
				/* translators: %s: the rows shown. */
				__( 'Showing the first %s rows. Narrow the search or the filters to see the others.', 'ai-eshop-optimizer' ),
				number_format_i18n( (int) $capped['shown'] )
			) );
			$html .= '<p class="rooster-admin-table__capped" role="note">' . Icons::ui( 'info', 14 ) . esc_html( $words ) . '</p>';
		}
		$local = $opts['rows_template'] ?? false;
		if ( true === $local || is_array( $local ) ) { // the whole list for the local engine (0.61.2, CONTRACT §8.2): the shown rows' twins, or every row
			$html .= '<template data-ra-rows="">' . self::table_rows( $columns, is_array( $local ) ? $local : $rows, $select, $details, $move, $cards ) . '</template>';
		}
		foreach ( is_array( $opts['choices'] ?? null ) ? $opts['choices'] : array() as $list => $options ) { // the cells' shared lists (0.62.1)
			$html .= self::choices( (string) $list, (array) $options );
		}
		if ( $live ) { // what local() shows when nothing answers the search and the filters (0.62.0: R3's no-results state, Clear filters)
			$none  = is_array( $opts['local'] ) && '' !== (string) ( $opts['local']['none'] ?? '' ) ? (string) $opts['local']['none'] : States::state(
				'no-results',
				array(
					'compact' => true,
					'text'    => __( 'Try other words or fewer filters.', 'ai-eshop-optimizer' ), // 0.63.1: neutral ("a wider period" fits few tables)
					'action'  => self::button(
						__( 'Clear filters', 'ai-eshop-optimizer' ),
						array(
							'icon'  => 'x',
							'attrs' => array( 'data-ra-clear' => '' ),
						)
					),
				)
			);
			$html .= '<template data-ra-none="">' . $none . '</template>';
		}
		if ( $far ) { // a page that did not come (0.63.0): R3's failed state, Try again
			$html .= '<template data-ra-failed="">' . States::state(
				'failed',
				array(
					'compact' => true,
					'verb'    => __( 'load the rows', 'ai-eshop-optimizer' ),
					'text'    => __( 'Try again in a moment.', 'ai-eshop-optimizer' ),
					'action'  => self::button(
						__( 'Try again', 'ai-eshop-optimizer' ),
						array(
							'icon'  => 'refresh-cw',
							'attrs' => array( 'data-ra-retry' => '' ),
						)
					),
				)
			) . '</template>';
		}
		$foot = $sizer . (string) ( $opts['footer'] ?? '' ); // the glue draws its pager after them
		if ( '' !== $foot ) {
			$html .= '<div class="rooster-admin-table__footer">' . $foot . '</div>';
		}
		return $island ? '<div class="rooster-admin rooster-admin-island">' . $html . '</div>' . $after . '</div>' : $html . '</div>' . $after;
	}

	/**
	 * A table's rows as `<tr>`s (0.61.2: shared by the shown rows and the template's, so the two cannot differ).
	 *
	 * @param array<int, array<string, mixed>> $columns The columns.
	 * @param array<int, mixed>                $rows    The rows (Ui::table()'s).
	 * @param bool                             $select  Whether each row starts with its checkbox.
	 * @param bool                             $details Whether each row has its Details button (0.64.0).
	 * @param array<string, mixed>|null        $move    move_conf()'s (0.65.0): each row's grip first, its key on it.
	 * @param bool                             $cards   0.73.0: a card per row: each cell but the first and the actions
	 *                                                  carries its column's name (data-ra-label), the card line's label.
	 */
	private static function table_rows( array $columns, array $rows, bool $select, bool $details = false, ?array $move = null, bool $cards = false ): string {
		$html  = '';
		$width = count( $columns ) + ( $select ? 1 : 0 ) + ( $details ? 1 : 0 ) + ( null !== $move ? 1 : 0 );
		foreach ( $rows as $row ) {
			if ( ! is_array( $row ) ) {
				continue;
			}
			if ( isset( $row['_span'] ) ) { // 0.65.2: a row across the table, a note (or a section label); the engine keeps it with the row above it, as a details row
				$label = 'label' === ( $row['_span_kind'] ?? '' );
				$html .= '<tr class="rooster-admin-table__detail is-span' . ( $label ? ' is-label' : '' ) . '"' . self::row_attrs( $row['_attrs'] ?? null ) . '><td class="rooster-admin-table__td is-span" colspan="' . $width . '">' . (string) $row['_span'] . '</td></tr>';
				continue;
			}
			if ( '' !== (string) ( $row['_group'] ?? '' ) ) { // a group heading row (a tree's branch): the label across every column, indented by its depth
				$html .= '<tr class="rooster-admin-table__row is-group is-depth-' . (int) ( $row['_depth'] ?? 0 ) . '"' . self::row_attrs( $row['_attrs'] ?? null ) . '><td class="rooster-admin-table__td is-group" colspan="' . $width . '">' . Icons::ui( 'caret', 14 ) . esc_html( (string) $row['_group'] ) . ( '' !== (string) ( $row['_note'] ?? '' ) ? ' <span class="rooster-admin-table__sub">' . esc_html( (string) $row['_note'] ) . '</span>' : '' ) . '</td></tr>';
				continue;
			}
			$key    = (string) ( $row['_id'] ?? '' );
			$locked = null !== $move ? (string) ( $row['_locked'] ?? '' ) : '';
			$item   = null !== $move && '' !== $key ? array( // 0.65.0: a row that moves (assets/board.js), its zone a fence, a locked one a fixed point
				'data-ra-item'   => $key,
				'data-ra-locked' => '' !== $locked ? '' : null,
				'data-ra-zone'   => '' !== (string) ( $row['_zone'] ?? '' ) ? (string) $row['_zone'] : null,
				'data-ra-name'   => self::row_name( $row, $columns ), // the Move menu's name
			) : array();
			$html .= '<tr class="rooster-admin-table__row' . ( ! empty( $row['_selected'] ) ? ' is-selected' : '' ) . ( '' !== $locked ? ' is-locked' : '' ) . ( isset( $row['_depth'] ) ? ' is-depth-' . (int) $row['_depth'] : '' ) . ( '' !== (string) ( $row['_tone'] ?? '' ) ? ' is-' . esc_attr( self::tone( (string) $row['_tone'] ) ) : '' ) . '"' . ( '' !== $key ? ' data-ra-row="' . esc_attr( $key ) . '"' : '' ) . self::attrs( $item ) . self::row_attrs( $row['_attrs'] ?? null ) . '>';
			if ( null !== $move ) { // the row's grip, or a lock that says why it keeps its place (FR7); its key posted in order with `name`
				$html .= '<td class="rooster-admin-table__td is-move">' . ( array() === $item ? '' : ( '' !== $locked
					? '<span class="rooster-admin-grip is-locked" role="img" tabindex="0" aria-label="' . esc_attr( $locked ) . '" data-ra-tip="' . esc_attr( $locked ) . '">' . Icons::svg( 'lock', 15 ) . '</span>'
					/* translators: %s: the row's name. */
					: Fields::item_grip( sprintf( __( 'Move "%s": drag it, use the arrow keys, or press Enter for the Move menu', 'ai-eshop-optimizer' ), self::row_name( $row, $columns ) ) ) )
					. ( '' !== $move['name'] ? '<input type="hidden" name="' . esc_attr( $move['name'] ) . '[]" value="' . esc_attr( $key ) . '" />' : '' ) ) . '</td>';
			}
			if ( $select ) {
				$html .= '<td class="rooster-admin-table__td is-check"><input type="checkbox" name="ids[]" value="' . esc_attr( (string) ( $row['_id'] ?? '' ) ) . '" aria-label="' . esc_attr__( 'Select this row', 'ai-eshop-optimizer' ) . '"' . ( ! empty( $row['_selected'] ) ? ' checked' : '' ) . ' /></td>';
			}
			$panel = $details && '' !== (string) ( $row['_detail'] ?? '' ) ? wp_unique_id( 'rooster-admin-detail-' ) : '';
			if ( $details ) { // 0.64.0: the row's Details button (aria-expanded), its panel the row after it
				/* translators: %s: the row's name. */
				$html .= '<td class="rooster-admin-table__td is-detail">' . ( '' !== $panel ? '<button type="button" class="rooster-admin-table__expand" aria-expanded="false" aria-controls="' . esc_attr( $panel ) . '" data-ra-detail="" aria-label="' . esc_attr( sprintf( __( 'Details of %s', 'ai-eshop-optimizer' ), self::row_name( $row, $columns ) ) ) . '">' . Icons::ui( 'chevron', 14 ) . '</button>' : '' ) . '</td>';
			}
			$first   = true;
			$covered = 0; // 0.65.2: the columns a cell's colspan covers print nothing in this row
			foreach ( $columns as $col ) {
				if ( $covered > 0 ) {
					--$covered;
					continue;
				}
				$key   = (string) ( $col['key'] ?? '' );
				$type  = (string) ( $col['type'] ?? 'text' );
				$cell  = $row[ $key ] ?? '';
				$span  = is_array( $cell ) && (int) ( $cell['colspan'] ?? 1 ) > 1 ? (int) $cell['colspan'] : 1;
				$covered = $span - 1;
				if ( 'actions' === $type && is_array( $cell ) && isset( $cell[0] ) ) { // the row's buttons (FR17, 0.61.0)
					$cell = Guidance::row_buttons( $cell, self::row_name( $row, $columns ) );
				}
				$tone  = is_array( $cell ) && 'status' !== $type && '' !== (string) ( $cell['tone'] ?? '' ) ? ' is-tone-' . self::tone( (string) $cell['tone'] ) : ''; // a cell's own tone (0.62.0)
				$said  = '';
				if ( '' === $tone && ! empty( $col['bands'] ) ) { // 0.65.7: its column's band, the tone said after the value
					$at  = self::band_value( $row, $key, $cell );
					$hit = null !== $at ? self::band( $at, self::bands( $col ) ) : null;
					if ( null !== $hit ) {
						$tone = '' !== $hit['tone'] ? ' is-tone-' . $hit['tone'] : '';
						$said = '' !== $hit['label'] ? '<span class="screen-reader-text">, ' . esc_html( $hit['label'] ) . '</span>' : '';
					}
				}
				if ( 'image' === $type && ! ( is_array( $cell ) && isset( $cell['html'] ) ) ) {
					$cell = array( 'html' => self::thumb( $cell, $col, $row, $columns ) ); // a thumbnail (0.62.1)
				}
				if ( 'radio' === $type && is_array( $cell ) && ! isset( $cell['html'] ) ) { // one choice per group (0.64.0)
					/* translators: %s: the row's name. */
					$said = '' !== (string) ( $cell['label'] ?? '' ) ? (string) $cell['label'] : sprintf( __( 'Choose %s', 'ai-eshop-optimizer' ), self::row_name( $row, $columns ) );
					$cell = array( 'html' => '<label class="rooster-admin-check is-bare"><input type="radio" name="' . esc_attr( (string) ( $cell['name'] ?? '' ) ) . '" value="' . esc_attr( (string) ( $cell['value'] ?? '' ) ) . '"' . ( ! empty( $cell['checked'] ) ? ' checked' : '' ) . ( ! empty( $cell['disabled'] ) ? ' disabled' : '' ) . ' /><span class="screen-reader-text">' . esc_html( $said ) . '</span></label>' );
				}
				$tip   = is_array( $cell ) && '' !== (string) ( $cell['tip'] ?? '' ) ? ' ' . Guidance::tip( (string) $cell['tip'], sprintf( /* translators: 1: a column, 2: a row. */ __( '%1$s of %2$s', 'ai-eshop-optimizer' ), (string) ( $col['label'] ?? '' ), self::row_name( $row, $columns ) ) ) : ''; // 0.63.1
				$html .= '<td class="rooster-admin-table__td is-' . esc_attr( $type ) . ( $first ? ' is-first' : '' ) . self::col_classes( $col ) . $tone . '"' . ( $cards && ! $first && 'actions' !== $type ? ' data-ra-label="' . esc_attr( (string) ( $col['label'] ?? '' ) ) . '"' : '' ) . ( $span > 1 ? ' colspan="' . $span . '"' : '' ) . '>' . self::cell( $type, $cell ) . $said . $tip;
				if ( $first && '' !== (string) ( $row['_actions'] ?? '' ) ) {
					$actions = (string) $row['_actions']; // Ui::row_actions() brings its own wrapper; bare links get one
					$html   .= str_starts_with( $actions, '<div class="rooster-admin-table__actions">' ) ? $actions : '<div class="rooster-admin-table__actions">' . $actions . '</div>';
				}
				$html .= '</td>';
				$first = false;
			}
			$html .= '</tr>';
			if ( '' !== $panel ) {
				$html .= '<tr class="rooster-admin-table__detail" id="' . esc_attr( $panel ) . '" hidden><td class="rooster-admin-table__td is-panel" colspan="' . $width . '">' . (string) $row['_detail'] . '</td></tr>';
			}
		}
		return $html;
	}

	/**
	 * A row's own attributes (0.61.2, `_attrs`): `data-*` only (the engine's data-ra-f, data-ra-s, data-ra-text, a
	 * product's own data-*), escaped; a list or a map is printed as JSON, true bare, null and false left out;
	 * `data-ra-row` stays the row's `_id`.
	 *
	 * @param mixed $attrs name => value.
	 */
	private static function row_attrs( $attrs ): string {
		if ( ! is_array( $attrs ) ) {
			return '';
		}
		$keep = array();
		foreach ( $attrs as $name => $value ) {
			$name = strtolower( (string) $name );
			if ( 'data-ra-row' === $name || 1 !== preg_match( '/^data-[a-z0-9][a-z0-9_.-]*$/', $name ) ) {
				continue;
			}
			$keep[ $name ] = is_array( $value ) || is_object( $value ) ? (string) wp_json_encode( $value ) : ( is_scalar( $value ) && ! is_bool( $value ) ? (string) $value : $value );
		}
		return self::attrs( $keep );
	}

	/**
	 * A column's width and alignment classes (0.63.1): min, or xs 6rem, sm 10rem, md 16rem, lg 24rem; start, center, end
	 * over the type's own alignment.
	 *
	 * @param array<string, mixed> $col The column.
	 */
	private static function col_classes( array $col ): string {
		$width = (string) ( $col['width'] ?? '' );
		$align = (string) ( $col['align'] ?? '' );
		return ( 'min' === $width ? ' is-min' : ( in_array( $width, array( 'xs', 'sm', 'md', 'lg' ), true ) ? ' is-w-' . $width : '' ) )
			. ( in_array( $align, array( 'start', 'center', 'end' ), true ) ? ' is-' . $align : '' );
	}

	/**
	 * The row of group headings over the column heads (0.72.0, TABLES-PLAN 1c: a grid's "Difficulty" over 1 to 5): a
	 * heading cell (scope colgroup) over each run of columns that share a `group`, a blank cell over every other column
	 * and over each cell before the first column's (a td: an empty th fails axe). The first column never groups (a
	 * grid's row label) and keeps a cell of its own, which sticks with sticky_first. Each cell says its places
	 * (data-ra-places), so table.js keeps the spans right when the chooser or the width hides a column; here the spans
	 * are right for what is hidden at the first paint. '' without a group.
	 *
	 * @param array<int, array<string, mixed>> $columns The columns.
	 * @param array<string, bool>              $lead    The cells before the first column's, in order: move, check, detail.
	 * @param array<int, bool>                 $hidden  The places hidden now (the chooser's), keyed.
	 * @param bool                             $stick   sticky_first: the first column's blank sticks with it.
	 */
	private static function group_row( array $columns, array $lead, array $hidden, bool $stick ): string {
		$any = false;
		foreach ( $columns as $col ) {
			if ( '' !== (string) ( $col['group'] ?? '' ) ) {
				$any = true;
				break;
			}
		}
		if ( ! $any ) {
			return '';
		}
		$html  = '<tr class="rooster-admin-table__groups">';
		$place = 0;
		foreach ( $lead as $kind => $on ) {
			if ( $on ) {
				++$place;
				$html .= '<td class="rooster-admin-table__th is-groupgap is-' . $kind . '" data-ra-places="' . $place . '"' . ( isset( $hidden[ $place ] ) ? ' hidden' : '' ) . '></td>';
			}
		}
		$n = count( $columns );
		for ( $i = 0; $i < $n; $i++ ) {
			$group = (string) ( $columns[ $i ]['group'] ?? '' );
			if ( '' === $group || 0 === $i ) {
				++$place;
				$html .= '<td class="rooster-admin-table__th is-groupgap' . ( $stick && 0 === $i ? ' is-first' : '' ) . '" data-ra-places="' . $place . '"' . ( isset( $hidden[ $place ] ) ? ' hidden' : '' ) . '></td>';
				continue;
			}
			$places = array();
			$j      = $i;
			while ( $j < $n && $group === (string) ( $columns[ $j ]['group'] ?? '' ) ) {
				$places[] = ++$place;
				++$j;
			}
			$shown = count( array_filter( $places, static fn( int $p ): bool => ! isset( $hidden[ $p ] ) ) );
			$html .= '<th class="rooster-admin-table__th is-grouphead" scope="colgroup" colspan="' . max( 1, $shown ) . '" data-ra-places="' . implode( ',', $places ) . '"' . ( 0 === $shown ? ' hidden' : '' ) . '>' . esc_html( $group ) . '</th>';
			$i     = $j - 1;
		}
		return $html . '</tr>';
	}

	/**
	 * A sort link's type for the engine (0.62.0): `sort_type`, else the column's (num: number, date, else text).
	 *
	 * @param array<string, mixed> $col The column.
	 */
	private static function sort_type( array $col ): string {
		$type = (string) ( $col['sort_type'] ?? '' );
		if ( in_array( $type, array( 'number', 'date', 'text' ), true ) ) {
			return $type;
		}
		$type = (string) ( $col['type'] ?? 'text' );
		return 'num' === $type ? 'number' : ( 'date' === $type ? 'date' : 'text' );
	}

	/**
	 * A local table's settings for roosterAdminTable.local() (0.62.0), with the words in the site's language.
	 *
	 * @param array<string, mixed> $local Ui::table()'s `local` (or `remote`).
	 * @param bool                 $far   0.63.0: a remote table (its route, scope, context and choices' route).
	 * @param array<int, mixed>    $decl  0.64.0: the declared filters (their kinds for the engine and the chips).
	 * @param string               $caption 0.74.3: the table's caption; without a `label` of its own the pager is named
	 *                                      after it ("Pages of Learners"), so two paging tables on one screen never
	 *                                      give two navs of one name (Rooster One's ratings screen, axe landmark-unique).
	 * @return array<string, mixed>
	 */
	private static function local_config( array $local, bool $far = false, array $decl = array(), string $caption = '' ): array {
		$sort = is_array( $local['sort'] ?? null ) && '' !== (string) ( $local['sort']['key'] ?? '' ) ? array(
			'key' => (string) $local['sort']['key'],
			'dir' => 'desc' === ( $local['sort']['dir'] ?? '' ) ? 'desc' : 'asc',
		) : null;
		$keys = array();
		foreach ( array( 's', 'orderby', 'order', 'paged', 'per_page' ) as $key ) {
			if ( '' !== (string) ( $local['keys'][ $key ] ?? '' ) ) {
				$keys[ $key ] = (string) $local['keys'][ $key ];
			}
		}
		$sizes = array_values( array_filter( array_map( 'intval', (array) ( $local['sizes'] ?? array() ) ), static fn( int $n ): bool => $n > 0 ) );
		return array(
			'form'    => ! $far && ! empty( $local['form'] ),
			'remote'  => $far ? array(
				'url'     => esc_url_raw( (string) $local['url'] ),
				'nonce'   => (string) ( $local['nonce'] ?? '' ),
				'scope'   => (object) array_map( 'strval', array_filter( (array) ( $local['scope'] ?? array() ), 'is_scalar' ) ),
				'context' => 'storefront' === ( $local['context'] ?? '' ) ? 'storefront' : 'admin',
				'options' => esc_url_raw( (string) ( $local['options'] ?? '' ) ),
				'current' => ! empty( $local['options_current'] ), // 0.65.6: the choices printed are this view's: no request at load
			) : null,
			'prefix'  => preg_replace( '/[^A-Za-z0-9_-]/', '', (string) ( $local['prefix'] ?? '' ) ),
			'total'   => max( 0, (int) ( $local['total'] ?? 0 ) ),
			'sizes'   => $sizes,
			'size'    => max( 0, (int) ( $local['size'] ?? ( $sizes[0] ?? 0 ) ) ), // 0.65.3: with sizes and no size, the first
			'words'   => ! empty( $local['words'] ),
			'tie'     => in_array( $local['tie'] ?? '', array( 'dir', 'asc' ), true ) ? (string) $local['tie'] : '',
			'sort'    => $sort,
			'paged'   => max( 1, (int) ( $local['paged'] ?? 1 ) ),
			'keys'    => (object) $keys,
			'labels'  => array(
				/* translators: %s: the number of items. */
				'one'      => _n( '%s item', '%s items', 1, 'ai-eshop-optimizer' ),
				/* translators: %s: the number of items. */
				'many'     => _n( '%s item', '%s items', 2, 'ai-eshop-optimizer' ),
				/* translators: %s: the table's caption. */
				'pages'    => (string) ( $local['label'] ?? ( '' !== $caption ? sprintf( __( 'Pages of %s', 'ai-eshop-optimizer' ), $caption ) : __( 'Pages', 'ai-eshop-optimizer' ) ) ),
				'prev'     => __( 'Previous page', 'ai-eshop-optimizer' ),
				'next'     => __( 'Next page', 'ai-eshop-optimizer' ),
				/* translators: %s: a page number. */
				'page'     => __( 'Page %s', 'ai-eshop-optimizer' ),
				/* translators: %s: the number of rows ticked (one). */
				'chosen'   => _n( '%s item selected', '%s items selected', 1, 'ai-eshop-optimizer' ),
				/* translators: %s: the number of rows ticked (none or several). */
				'selected' => _n( '%s item selected', '%s items selected', 2, 'ai-eshop-optimizer' ),
				'tick'     => __( 'Tick rows first', 'ai-eshop-optimizer' ),
				/* translators: %s: how many rows match the search and the filters. */
				'all'      => __( 'Select all %s', 'ai-eshop-optimizer' ),
				/* translators: %s: how many rows match the search and the filters. */
				'every'    => __( 'All %s selected', 'ai-eshop-optimizer' ),
				'loading'  => __( 'Loading…', 'ai-eshop-optimizer' ),
				/* translators: 1: a filter, 2: its value ("Status: Low"). */
				'chip'     => __( '%1$s: %2$s', 'ai-eshop-optimizer' ),
				/* translators: %s: an active filter, "Status: Low". */
				'remove'   => __( 'Remove %s', 'ai-eshop-optimizer' ),
				'clear'    => __( 'Clear filters', 'ai-eshop-optimizer' ),
				/* translators: %s: a range's start. */
				'from'     => __( 'from %s', 'ai-eshop-optimizer' ),
				/* translators: %s: a range's end. */
				'to'       => __( 'to %s', 'ai-eshop-optimizer' ),
			),
			'filters' => (object) Filters::specs( $decl ),
			'dates'   => Filters::date_conf( $decl ), // 0.65.0: a date range's chip in the site's date format; null without one
			'close'   => array() !== $decl ? Icons::ui( 'close', 12 ) : '',
			'chevron' => Icons::ui( 'chevron', 14 ),
		);
	}

	/**
	 * A table's thumbnail (0.62.1, the `image` column): a box of a fixed size (no row moves while it loads), the image in
	 * it lazy and async, its placeholder under it (an image that is missing, or fails to load, shows the placeholder:
	 * table.js marks it, never the browser's broken image). A click on it can act, the first of: `action` (a button with
	 * the product's hooks: data-ra-dialog opens one of the chrome's dialogs, or the product's script listens), `preview`
	 * (a button: table.js shows the larger image in a dialog), a link. A button is named "Preview <the image or the
	 * row>" or by its label; a described image's link by its alt; a decorative image's link repeats the row's own.
	 *
	 * @param mixed                            $cell    A URL, an attachment id, or {src or id, alt, url, preview (a URL,
	 *                                                  or true), action ({label (raw), attrs})}.
	 * @param array<string, mixed>             $col     The column: size, alt (a row key), link (a row key), preview
	 *                                                  (true, or the row key of the larger image's URL), action.
	 * @param array<string, mixed>             $row     The row.
	 * @param array<int, array<string, mixed>> $columns The columns (the row's name, for a link's).
	 */
	private static function thumb( $cell, array $col, array $row, array $columns ): string {
		$sizes = array(
			'sm' => 32,
			'md' => 40,
			'lg' => 56,
			'xl' => 80,
		);
		$size  = isset( $sizes[ $col['size'] ?? '' ] ) ? (string) $col['size'] : 'md';
		$px    = $sizes[ $size ];
		$data  = is_array( $cell ) ? $cell : ( is_int( $cell ) || ( is_string( $cell ) && ctype_digit( $cell ) && '' !== $cell ) ? array( 'id' => (int) $cell ) : array( 'src' => (string) $cell ) );
		$src   = (string) ( $data['src'] ?? '' );
		if ( '' === $src && (int) ( $data['id'] ?? 0 ) > 0 ) {
			$found = wp_get_attachment_image_src( (int) $data['id'], $px > 56 ? 'medium' : 'thumbnail' );
			$src   = is_array( $found ) ? (string) $found[0] : '';
		}
		$alt  = (string) ( $data['alt'] ?? ( '' !== (string) ( $col['alt'] ?? '' ) ? ( $row[ (string) $col['alt'] ] ?? '' ) : '' ) );
		$url  = (string) ( $data['url'] ?? ( '' !== (string) ( $col['link'] ?? '' ) ? ( $row[ (string) $col['link'] ] ?? '' ) : '' ) );
		$box  = '<span class="rooster-admin-table__thumb is-' . $size . '">' . Icons::ui( 'image', $px > 40 ? 20 : 16 )
			. ( '' !== $src ? '<img class="rooster-admin-table__img" src="' . esc_url( $src ) . '" alt="' . esc_attr( $alt ) . '" width="' . $px . '" height="' . $px . '" loading="lazy" decoding="async" />' : '' ) . '</span>';
		$who  = '' !== $alt ? $alt : self::row_name( $row, $columns );
		$who  = '' !== $who ? $who : __( 'Image', 'ai-eshop-optimizer' );
		$act  = is_array( $data['action'] ?? null ) ? $data['action'] : ( is_array( $col['action'] ?? null ) ? $col['action'] : null );
		if ( null !== $act ) { // the product's action: its hooks on a named button
			$attrs = is_array( $act['attrs'] ?? null ) ? $act['attrs'] : array();
			unset( $attrs['class'], $attrs['type'], $attrs['aria-label'] );
			return '<button type="button" class="rooster-admin-table__thumblink" aria-label="' . esc_attr( '' !== (string) ( $act['label'] ?? '' ) ? (string) $act['label'] : $who ) . '"' . self::attrs( $attrs ) . '>' . $box . '</button>';
		}
		$big = $data['preview'] ?? ( $col['preview'] ?? null );
		if ( is_string( $big ) && '' !== $big && ! isset( $data['preview'] ) ) {
			$big = (string) ( $row[ $big ] ?? '' ); // the column names the row key of the larger image
		}
		if ( true === $big ) {
			$big = (int) ( $data['id'] ?? 0 ) > 0 ? (string) wp_get_attachment_image_url( (int) $data['id'], 'large' ) : $src;
		}
		if ( is_string( $big ) && '' !== $big && '' !== $src ) { // the larger image, in table.js's dialog
			/* translators: %s: the image's description, or its row's name. */
			$name = sprintf( __( 'Preview %s', 'ai-eshop-optimizer' ), $who );
			return '<button type="button" class="rooster-admin-table__thumblink" aria-label="' . esc_attr( $name ) . '" aria-haspopup="dialog" data-ra-preview="' . esc_url( $big ) . '" data-ra-preview-alt="' . esc_attr( '' !== $alt ? $alt : $who ) . '" data-ra-preview-close="' . esc_attr__( 'Close', 'ai-eshop-optimizer' ) . '">' . $box . '</button>';
		}
		if ( '' === $url ) {
			return $box;
		}
		// A decorative thumbnail's link repeats the row's own (its title): the mouse's convenience, out of the keyboard's
		// way and unread; a described image's link is named by its alt.
		return '' === $alt
			? '<a class="rooster-admin-table__thumblink" href="' . esc_url( $url ) . '" tabindex="-1" aria-hidden="true">' . $box . '</a>'
			: '<a class="rooster-admin-table__thumblink" href="' . esc_url( $url ) . '">' . $box . '</a>';
	}

	/**
	 * A row's name for its buttons (0.61.0): `_name`, else its first cell's title or text; 0.62.1: the first column that
	 * says what the row is (not a picture, a yes or no, a bar, a box or the buttons: a thumbnail first named its row with
	 * its URL; 0.64.0: nor a radio, and an empty cell passes on to the next), '' when none does.
	 *
	 * @param array<string, mixed>             $row     The row.
	 * @param array<int, array<string, mixed>> $columns The columns.
	 */
	private static function row_name( array $row, array $columns ): string {
		if ( '' !== (string) ( $row['_name'] ?? '' ) ) {
			return (string) $row['_name'];
		}
		foreach ( $columns as $col ) { // 0.64.0: the first that says something (a radio's column says nothing)
			if ( in_array( (string) ( $col['type'] ?? 'text' ), array( 'image', 'boolean', 'progress', 'check', 'actions', 'radio' ), true ) ) {
				continue;
			}
			$cell = $row[ (string) ( $col['key'] ?? '' ) ] ?? '';
			$html = 'html' === (string) ( $col['type'] ?? 'text' ); // a raw text otherwise (cell() escapes it)
			if ( is_array( $cell ) ) {
				$html = isset( $cell['html'] ) && ! isset( $cell['title'] );
				$cell = isset( $cell['title'] ) ? (string) $cell['title'] : (string) ( $cell['html'] ?? '' );
			}
			$name = trim( $html ? html_entity_decode( wp_strip_all_tags( (string) $cell ), ENT_QUOTES, 'UTF-8' ) : (string) $cell );
			if ( '' !== $name ) {
				return $name;
			}
		}
		return '';
	}

	/**
	 * One cell by its column's type.
	 *
	 * @param string $type The type.
	 * @param mixed  $cell The value: a string; for `text` an array {title, sub (a second line), url}; for `status`
	 *                     an array {label, tone}; for `progress` an int or {value, label}; for `html` escaped HTML;
	 *                     0.62.0: for `boolean` a yes or no (true, 1, '1', 'yes', 'on'; false, 0, '0', 'no', 'off'; ''
	 *                     or null: unknown, empty) or {value, label (raw: the words read out instead of Yes or No)};
	 *                     for `code` a text in monospace; num, date and code take {value} as well as {title};
	 *                     in any column, {html} prints its escaped HTML as is (0.52.0: Ui::editable() in a number or
	 *                     date column keeps the column's alignment).
	 */
	private static function cell( string $type, $cell ): string {
		if ( is_array( $cell ) && isset( $cell['html'] ) ) {
			return (string) $cell['html']; // the caller's escaped HTML in a typed column, its alignment kept (an editable cell, 0.52.0)
		}
		switch ( $type ) {
			case 'status':
				$label = is_array( $cell ) ? (string) ( $cell['label'] ?? '' ) : (string) $cell;
				return '' === $label ? '' : self::badge( $label, is_array( $cell ) ? (string) ( $cell['tone'] ?? 'mono' ) : 'mono', array( 'dot' => true ) );
			case 'progress':
				$value = is_array( $cell ) ? (float) ( $cell['value'] ?? 0 ) : (float) $cell;
				return self::progress( $value, 100, array( 'label' => is_array( $cell ) ? (string) ( $cell['label'] ?? '' ) : '' ) );
			case 'num':
			case 'date':
				return is_array( $cell ) ? esc_html( (string) ( $cell['title'] ?? $cell['value'] ?? '' ) ) : esc_html( (string) $cell );
			case 'code':
				$text = is_array( $cell ) ? (string) ( $cell['title'] ?? $cell['value'] ?? '' ) : (string) $cell;
				return '' === $text ? '' : '<code class="rooster-admin-table__code">' . esc_html( $text ) . '</code>';
			case 'boolean':
				$value = is_array( $cell ) ? ( $cell['value'] ?? null ) : $cell;
				if ( null === $value || '' === $value ) {
					return '';
				}
				$yes  = ! in_array( is_string( $value ) ? strtolower( trim( $value ) ) : $value, array( false, 0, '0', 'no', 'off', 'false' ), true );
				$word = is_array( $cell ) && '' !== (string) ( $cell['label'] ?? '' ) ? (string) $cell['label'] : ( $yes ? __( 'Yes', 'ai-eshop-optimizer' ) : __( 'No', 'ai-eshop-optimizer' ) );
				return '<span class="rooster-admin-table__bool is-' . ( $yes ? 'yes' : 'no' ) . '">' . Icons::ui( $yes ? 'check' : 'minus', 14 ) . '<span class="screen-reader-text">' . esc_html( $word ) . '</span></span>';
			case 'html':
			case 'actions':
				return (string) $cell;
			default:
				if ( is_array( $cell ) ) {
					$title = esc_html( (string) ( $cell['title'] ?? '' ) );
					$icon  = '' !== (string) ( $cell['icon'] ?? '' ) ? Icons::svg( (string) $cell['icon'], 15, 'rooster-admin-table__icon' ) : '';
					$html  = '' !== (string) ( $cell['url'] ?? '' ) ? '<a class="rooster-admin-table__title" href="' . esc_url( (string) $cell['url'] ) . '">' . $icon . $title . '</a>' : '<span class="rooster-admin-table__title">' . $icon . $title . '</span>';
					if ( '' !== (string) ( $cell['avatar'] ?? '' ) ) { // initials in a disc before the title (a person)
						$html = '<span class="rooster-admin-table__person"><span class="rooster-admin-table__avatar" aria-hidden="true">' . esc_html( (string) $cell['avatar'] ) . '</span><span>' . $html . ( '' !== (string) ( $cell['sub'] ?? '' ) ? '<span class="rooster-admin-table__sub">' . esc_html( (string) $cell['sub'] ) . '</span>' : '' ) . '</span></span>';
						return $html;
					}
					return $html . ( '' !== (string) ( $cell['sub'] ?? '' ) ? '<span class="rooster-admin-table__sub">' . esc_html( (string) $cell['sub'] ) . '</span>' : '' );
				}
				return esc_html( (string) $cell );
		}
	}

	/**
	 * A progress bar (native `<progress>`), with an optional label and the value as text.
	 *
	 * @param float                $value The value.
	 * @param float                $max   The maximum.
	 * @param array<string, mixed> $opts  label (raw), tone, show_value (true: "42 %"), id.
	 */
	public static function progress( float $value, float $max = 100, array $opts = array() ): string {
		$max   = $max > 0 ? $max : 100;
		$value = max( 0, min( $value, $max ) );
		$pct   = (int) round( 100 * $value / $max );
		$id    = (string) ( $opts['id'] ?? '' );
		return '<span class="rooster-admin-progress is-' . esc_attr( self::tone( (string) ( $opts['tone'] ?? 'primary' ), 'primary' ) ) . '">'
			. ( '' !== (string) ( $opts['label'] ?? '' ) ? '<span class="rooster-admin-progress__label"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '-label"' : '' ) . '>' . esc_html( (string) $opts['label'] ) . '</span>' : '' )
			. '<progress class="rooster-admin-progress__bar" value="' . esc_attr( (string) $value ) . '" max="' . esc_attr( (string) $max ) . '"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '"' . ( '' !== (string) ( $opts['label'] ?? '' ) ? ' aria-labelledby="' . esc_attr( $id ) . '-label"' : '' ) : ' aria-label="' . esc_attr( '' !== (string) ( $opts['label'] ?? '' ) ? (string) $opts['label'] : __( 'Progress', 'ai-eshop-optimizer' ) ) . '"' ) . '>' . esc_html( (string) $pct ) . '%</progress>'
			. ( empty( $opts['show_value'] ) ? '' : '<span class="rooster-admin-progress__value">' . esc_html( (string) $pct ) . ' %</span>' ) . '</span>';
	}

	/**
	 * Steps: the stages of a process, the current one marked, the done ones ticked. A wizard's rail (0.63.1): a step may
	 * be {label, url}; a done step with a URL is a link back to it, the current one is `aria-current="step"` and never a
	 * link, a later one never a link (it is not reached yet).
	 *
	 * @param array<int, string|array<string, mixed>> $steps   The labels (raw), or {label (raw), url}.
	 * @param int                                     $current The current step (1-based).
	 * @param array<string, mixed>                    $opts    label (the nav's name).
	 */
	public static function steps( array $steps, int $current, array $opts = array() ): string {
		$html = '<ol class="rooster-admin-steps" aria-label="' . esc_attr( (string) ( $opts['label'] ?? __( 'Steps', 'ai-eshop-optimizer' ) ) ) . '">';
		$n    = 0;
		foreach ( $steps as $step ) {
			++$n;
			$label = is_array( $step ) ? (string) ( $step['label'] ?? '' ) : (string) $step;
			$url   = is_array( $step ) && $n < $current ? (string) ( $step['url'] ?? '' ) : ''; // only a done step links back
			$state = $n < $current ? 'is-done' : ( $n === $current ? 'is-current' : '' );
			$inner = '<span class="rooster-admin-steps__num" aria-hidden="true">' . ( $n < $current ? Icons::ui( 'check', 12 ) : esc_html( (string) $n ) ) . '</span><span class="rooster-admin-steps__label">' . esc_html( $label ) . '</span>';
			$html .= '<li class="rooster-admin-steps__step' . ( '' !== $state ? ' ' . $state : '' ) . '"' . ( $n === $current ? ' aria-current="step"' : '' ) . '>'
				. ( '' !== $url ? '<a class="rooster-admin-steps__link" href="' . esc_url( $url ) . '">' . $inner . '</a>' : $inner ) . '</li>';
		}
		return $html . '</ol>';
	}

	/**
	 * Stars: a rating shown (read-only) or taken (buttons with `aria-pressed`, as the feedback dialog's).
	 *
	 * @param int                  $value The rating.
	 * @param array<string, mixed> $opts  max (5), input (true: buttons that set the rating; `name` for the hidden
	 *                                    field), label (the group's name), sm.
	 */
	public static function stars( int $value, array $opts = array() ): string {
		$max   = max( 1, (int) ( $opts['max'] ?? 5 ) );
		$value = max( 0, min( $value, $max ) );
		$input = ! empty( $opts['input'] );
		$html  = '<span class="rooster-admin-stars' . ( ! empty( $opts['sm'] ) ? ' is-sm' : '' ) . '" role="' . ( $input ? 'group' : 'img' ) . '" aria-label="' . esc_attr( (string) ( $opts['label'] ?? sprintf(
			/* translators: 1: the rating, 2: the maximum. */
			__( '%1$d out of %2$d', 'ai-eshop-optimizer' ),
			$value,
			$max
		) ) ) . '">';
		for ( $i = 1; $i <= $max; $i++ ) {
			$on = $i <= $value;
			if ( $input ) {
				/* translators: 1: the rating, 2: the maximum. */
				$html .= '<button type="button" class="rooster-admin-stars__star' . ( $on ? ' is-on' : '' ) . '" data-v="' . $i . '" aria-pressed="' . ( $on ? 'true' : 'false' ) . '" aria-label="' . esc_attr( sprintf( __( '%1$d out of %2$d', 'ai-eshop-optimizer' ), $i, $max ) ) . '">' . Icons::ui( 'star', 18 ) . '</button>';
			} else {
				$html .= '<span class="rooster-admin-stars__star' . ( $on ? ' is-on' : '' ) . '" aria-hidden="true">' . Icons::ui( 'star', 16 ) . '</span>';
			}
		}
		if ( $input && '' !== (string) ( $opts['name'] ?? '' ) ) {
			$html .= '<input type="hidden" name="' . esc_attr( (string) $opts['name'] ) . '" value="' . esc_attr( (string) $value ) . '" />';
		}
		return $html . '</span>';
	}

	/**
	 * A stat tile: a label, a big value, a delta with its direction, an optional sparkline.
	 *
	 * @param string               $label The label (raw).
	 * @param string               $value The value (raw, formatted by the caller).
	 * @param array<string, mixed> $opts  delta (raw, e.g. "+12 %"), direction (up, down, flat), tone (the delta's
	 *                                    tone; default by direction), hint (raw small text), spark (list<float>),
	 *                                    icon (Lucide), attrs (on the tile: an id, a data-* hook a script reads;
	 *                                    0.42.0), tip (0.63.1, raw: what the figure counts and how, in R4's toggletip
	 *                                    after the label, Guidance::tip(): "About <label>").
	 */
	public static function stat( string $label, string $value, array $opts = array() ): string {
		$direction = in_array( $opts['direction'] ?? '', array( 'up', 'down', 'flat' ), true ) ? (string) $opts['direction'] : '';
		$tone      = self::tone( (string) ( $opts['tone'] ?? ( 'up' === $direction ? 'success' : ( 'down' === $direction ? 'destructive' : 'mono' ) ) ) );
		$tip       = (string) ( $opts['tip'] ?? '' );
		$html      = '<div' . self::attrs( self::merge_attrs( array( 'class' => 'rooster-admin-stat' ), $opts['attrs'] ?? null ) ) . '>'
			. '<div class="rooster-admin-stat__head">' . ( '' !== (string) ( $opts['icon'] ?? '' ) ? Icons::svg( (string) $opts['icon'], 16, 'rooster-admin-stat__icon' ) : '' ) . '<span class="rooster-admin-stat__label">' . esc_html( $label ) . '</span>'
			. ( '' !== $tip ? Guidance::tip( $tip, $label ) : '' ) . '</div>'
			. '<div class="rooster-admin-stat__row"><span class="rooster-admin-stat__value">' . esc_html( $value ) . '</span>';
		if ( '' !== (string) ( $opts['delta'] ?? '' ) ) {
			$html .= '<span class="rooster-admin-stat__delta is-' . esc_attr( $tone ) . '">' . ( 'up' === $direction ? Icons::svg( 'trending-up', 14 ) : ( 'down' === $direction ? Icons::svg( 'trending-down', 14 ) : '' ) ) . esc_html( (string) $opts['delta'] ) . '</span>';
		}
		$html .= '</div>';
		if ( is_array( $opts['spark'] ?? null ) && count( $opts['spark'] ) > 1 ) {
			$html .= self::chart_svg(
				array(
					'type'   => 'spark',
					'series' => array(
						array(
							'values' => $opts['spark'],
							'tone'   => $tone,
						),
					),
					'label'  => sprintf(
						/* translators: %s: the stat's label. */
						__( 'Trend of %s', 'ai-eshop-optimizer' ),
						$label
					),
				)
			);
		}
		if ( '' !== (string) ( $opts['hint'] ?? '' ) ) {
			$html .= '<p class="rooster-admin-stat__hint">' . esc_html( (string) $opts['hint'] ) . '</p>';
		}
		return $html . '</div>';
	}

	/**
	 * A chart as inline SVG, no script (chart_svg() since 0.75.0: chart() is the container a charting library draws
	 * into): bars (grouped), a line (with an area), a donut, a sparkline, a funnel (0.63.1: the steps of a pipeline as
	 * a list, each a bar proportional to the first: funnel()). The series wear the tones; the axes use the chrome's
	 * text colours.
	 *
	 * @param array<string, mixed> $spec type (bar, line, donut, spark, funnel), series (list of {label, values (list of
	 *                                   numbers), tone}; a funnel draws the first: its values are the steps' counts),
	 *                                   labels (the categories; a funnel's steps), label (the chart's accessible
	 *                                   name), height (px; default by type), legend (true), format (a sprintf
	 *                                   pattern for the values, e.g. '%s €'), max (the scale's top).
	 */
	public static function chart_svg( array $spec ): string {
		$type   = in_array( $spec['type'] ?? '', array( 'bar', 'line', 'donut', 'spark', 'funnel' ), true ) ? (string) $spec['type'] : 'bar';
		$series = array();
		$n      = 0;
		foreach ( is_array( $spec['series'] ?? null ) ? $spec['series'] : array() as $s ) {
			if ( ! is_array( $s ) || ! is_array( $s['values'] ?? null ) ) {
				continue;
			}
			++$n;
			$series[] = array(
				'label'  => (string) ( $s['label'] ?? '' ),
				'values' => array_values( array_map( 'floatval', $s['values'] ) ),
				'tone'   => self::tone( (string) ( $s['tone'] ?? '' ), '' ),
				'n'      => $n,
			);
		}
		$labels = array_values( array_map( 'strval', is_array( $spec['labels'] ?? null ) ? $spec['labels'] : array() ) );
		$name   = (string) ( $spec['label'] ?? __( 'Chart', 'ai-eshop-optimizer' ) );
		$format = (string) ( $spec['format'] ?? '%s' );
		$fmt    = static fn( float $v ): string => sprintf( $format, number_format_i18n( $v, floor( $v ) === $v ? 0 : 1 ) );
		$class  = static fn( array $s ): string => 'rooster-admin-chart__series is-s' . ( (int) $s['n'] ) . ( '' !== $s['tone'] ? ' is-' . $s['tone'] : '' );
		if ( 'funnel' === $type ) {
			return self::funnel( $series[0] ?? null, $labels, $name, $fmt, $class, ! empty( $spec['legend'] ) );
		}
		$legend = '';
		if ( ! empty( $spec['legend'] ) && 'spark' !== $type ) {
			$legend = '<ul class="rooster-admin-chart__legend">';
			foreach ( $series as $i => $s ) {
				$legend .= '<li class="' . esc_attr( $class( $s ) ) . '"><span class="rooster-admin-chart__swatch" aria-hidden="true"></span>' . esc_html( '' !== $s['label'] ? $s['label'] : ( $labels[ $i ] ?? '' ) ) . '</li>';
			}
			$legend .= '</ul>';
		}
		$body = '';
		if ( 'donut' === $type ) {
			$values = array();
			foreach ( $series as $s ) {
				$values[] = (float) ( $s['values'][0] ?? 0 );
			}
			$total = array_sum( $values );
			$r     = 40;
			$c     = 2 * M_PI * $r;
			$off   = 0.0;
			$body  = '<svg class="rooster-admin-chart__svg" viewBox="0 0 100 100" role="img" aria-label="' . esc_attr( $name ) . '"><title>' . esc_html( $name ) . '</title>';
			foreach ( $series as $i => $s ) {
				$v     = $total > 0 ? $values[ $i ] / $total : 0;
				$body .= '<circle class="' . esc_attr( $class( $s ) ) . '" cx="50" cy="50" r="' . $r . '" fill="none" stroke="currentColor" stroke-width="12" stroke-dasharray="' . esc_attr( number_format( $v * $c, 3, '.', '' ) . ' ' . number_format( $c, 3, '.', '' ) ) . '" stroke-dashoffset="' . esc_attr( number_format( -$off * $c, 3, '.', '' ) ) . '" transform="rotate(-90 50 50)"><title>' . esc_html( $s['label'] . ': ' . $fmt( $values[ $i ] ) ) . '</title></circle>';
				$off  += $v;
			}
			$body .= '<text class="rooster-admin-chart__total" x="50" y="50" text-anchor="middle" dominant-baseline="central">' . esc_html( $fmt( $total ) ) . '</text></svg>';
			return '<figure class="rooster-admin-chart is-donut">' . $body . $legend . '</figure>';
		}
		$w      = 'spark' === $type ? 120 : 600;
		$h      = (int) ( $spec['height'] ?? ( 'spark' === $type ? 32 : 220 ) );
		$padl   = 'spark' === $type ? 0 : 44;
		$padb   = 'spark' === $type ? 0 : 24;
		$padt   = 'spark' === $type ? 2 : 10;
		$max    = (float) ( $spec['max'] ?? 0 );
		$count  = 0;
		foreach ( $series as $s ) {
			$max   = max( $max, array() !== $s['values'] ? max( $s['values'] ) : 0 );
			$count = max( $count, count( $s['values'] ) );
		}
		$max   = $max > 0 ? $max : 1;
		$plotw = $w - $padl - ( 'spark' === $type ? 0 : 8 );
		$ploth = $h - $padt - $padb;
		$x     = static fn( int $i ) => $count > 1 ? $padl + $plotw * $i / ( $count - 1 ) : $padl + $plotw / 2;
		$y     = static fn( float $v ) => $padt + $ploth - $ploth * $v / $max;
		$body  = '<svg class="rooster-admin-chart__svg" viewBox="0 0 ' . $w . ' ' . $h . '" role="img" aria-label="' . esc_attr( $name ) . '"' . ( 'spark' === $type ? ' preserveAspectRatio="none"' : '' ) . '><title>' . esc_html( $name ) . '</title>';
		if ( 'spark' !== $type ) {
			for ( $g = 0; $g <= 4; $g++ ) {
				$gy    = $padt + $ploth * $g / 4;
				$body .= '<line class="rooster-admin-chart__grid" x1="' . $padl . '" y1="' . number_format( $gy, 1, '.', '' ) . '" x2="' . ( $w - 8 ) . '" y2="' . number_format( $gy, 1, '.', '' ) . '" stroke="currentColor" />'
					. '<text class="rooster-admin-chart__axis" x="' . ( $padl - 6 ) . '" y="' . number_format( $gy, 1, '.', '' ) . '" text-anchor="end" dominant-baseline="central">' . esc_html( $fmt( $max * ( 4 - $g ) / 4 ) ) . '</text>';
			}
			foreach ( $labels as $i => $label ) {
				if ( $i >= $count ) {
					break;
				}
				$lx    = 'bar' === $type ? $padl + $plotw * ( $i + 0.5 ) / max( 1, $count ) : $x( (int) $i );
				$body .= '<text class="rooster-admin-chart__axis" x="' . number_format( $lx, 1, '.', '' ) . '" y="' . ( $h - 6 ) . '" text-anchor="middle">' . esc_html( $label ) . '</text>';
			}
		}
		if ( 'bar' === $type ) {
			$groups = max( 1, $count );
			$gw     = $plotw / $groups;
			$bw     = $gw * 0.7 / max( 1, count( $series ) );
			foreach ( $series as $si => $s ) {
				foreach ( $s['values'] as $i => $v ) {
					$bx    = $padl + $gw * $i + $gw * 0.15 + $bw * $si;
					$body .= '<rect class="' . esc_attr( $class( $s ) ) . '" x="' . number_format( $bx, 1, '.', '' ) . '" y="' . number_format( $y( $v ), 1, '.', '' ) . '" width="' . number_format( max( 1, $bw - 2 ), 1, '.', '' ) . '" height="' . number_format( max( 0, $padt + $ploth - $y( $v ) ), 1, '.', '' ) . '" rx="2" fill="currentColor"><title>' . esc_html( ( $labels[ $i ] ?? '' ) . ( '' !== $s['label'] ? ' · ' . $s['label'] : '' ) . ': ' . $fmt( $v ) ) . '</title></rect>';
				}
			}
		} else {
			foreach ( $series as $s ) {
				$points = array();
				foreach ( $s['values'] as $i => $v ) {
					$points[] = number_format( $x( (int) $i ), 1, '.', '' ) . ',' . number_format( $y( $v ), 1, '.', '' );
				}
				if ( array() === $points ) {
					continue;
				}
				$first = explode( ',', $points[0] )[0];
				$last  = explode( ',', $points[ count( $points ) - 1 ] )[0];
				$base  = number_format( $padt + $ploth, 1, '.', '' );
				$body .= '<path class="' . esc_attr( $class( $s ) ) . ' is-area" d="M' . $first . ',' . $base . ' L' . implode( ' L', $points ) . ' L' . $last . ',' . $base . ' Z" fill="currentColor" opacity="0.12" />'
					. '<polyline class="' . esc_attr( $class( $s ) ) . '" points="' . esc_attr( implode( ' ', $points ) ) . '" fill="none" stroke="currentColor" stroke-width="' . ( 'spark' === $type ? 2 : 2.5 ) . '" stroke-linecap="round" stroke-linejoin="round"><title>' . esc_html( $s['label'] ) . '</title></polyline>';
				if ( 'spark' !== $type ) {
					foreach ( $s['values'] as $i => $v ) {
						$body .= '<circle class="' . esc_attr( $class( $s ) ) . '" cx="' . number_format( $x( (int) $i ), 1, '.', '' ) . '" cy="' . number_format( $y( $v ), 1, '.', '' ) . '" r="3" fill="currentColor"><title>' . esc_html( ( $labels[ $i ] ?? '' ) . ( '' !== $s['label'] ? ' · ' . $s['label'] : '' ) . ': ' . $fmt( $v ) ) . '</title></circle>';
					}
				}
			}
		}
		$body .= '</svg>';
		return '<figure class="rooster-admin-chart is-' . $type . '">' . $body . $legend . '</figure>';
	}

	/**
	 * A funnel (0.63.1, chart_svg()'s `funnel`): the steps of a pipeline, each a subset of the one before ("High-score
	 * targets → Push-reachable → Attempted → Reactivated"; a workflow's "Sent → Clicked → Ordered"). A list, read in
	 * order: each step's label, its count, its share of the step before and of the first ("62 % of the step before"),
	 * and a bar proportional to the first step (decorative SVG in the series' tone: the text carries every figure, so
	 * it reads without colour). A step at 0 is an empty bar, its share "—" (nothing to compare yet).
	 *
	 * @param array<string, mixed>|null $series The series (chart_svg()'s normalised first one): its values are the counts.
	 * @param array<int, string>        $labels The steps' labels (raw).
	 * @param string                    $name   The list's accessible name (raw).
	 * @param callable                  $fmt    Formats a count.
	 * @param callable                  $class  The series' classes.
	 * @param bool                      $legend Whether the series' label shows as a legend.
	 */
	private static function funnel( ?array $series, array $labels, string $name, callable $fmt, callable $class, bool $legend ): string {
		$series = $series ?? array(
			'label'  => '',
			'values' => array(),
			'tone'   => '',
			'n'      => 1,
		);
		$values = $series['values'];
		$first  = (float) ( $values[0] ?? 0 );
		$count  = max( count( $labels ), count( $values ) );
		$share  = static function ( float $part, float $whole ): string {
			$pct = 100 * $part / $whole;
			if ( $pct < 0.1 ) {
				return '< ' . number_format_i18n( 0.1, 1 ) . ' %';
			}
			return number_format_i18n( $pct, $pct >= 10 || floor( $pct ) === $pct ? 0 : 1 ) . ' %';
		};
		$items  = '';
		for ( $i = 0; $i < $count; $i++ ) {
			$v      = (float) ( $values[ $i ] ?? 0 );
			$before = (float) ( $values[ $i - 1 ] ?? 0 );
			$width  = $first > 0 ? max( 0.0, min( 100.0, 100 * $v / $first ) ) : 0.0;
			$shares = array();
			if ( $i > 0 && $v > 0 && $before > 0 ) {
				/* translators: %s: a share, "62 %". */
				$shares[] = sprintf( __( '%s of the step before', 'ai-eshop-optimizer' ), $share( $v, $before ) );
			}
			if ( $i > 1 && $v > 0 && $first > 0 ) {
				/* translators: %s: a share, "37 %". */
				$shares[] = sprintf( __( '%s of the first step', 'ai-eshop-optimizer' ), $share( $v, $first ) );
			}
			$text = array();
			foreach ( $shares as $s ) {
				$text[] = '<span class="rooster-admin-funnel__share">' . esc_html( $s ) . '</span>';
			}
			$items .= '<li class="rooster-admin-funnel__step' . ( $v > 0 ? '' : ' is-zero' ) . '">'
				. '<span class="rooster-admin-funnel__label">' . esc_html( (string) ( $labels[ $i ] ?? '' ) ) . '</span>'
				. '<span class="rooster-admin-funnel__count">' . esc_html( $fmt( $v ) ) . '</span>'
				. '<svg class="rooster-admin-funnel__bar" viewBox="0 0 100 8" preserveAspectRatio="none" aria-hidden="true" focusable="false">'
				. ( $width > 0 ? '<rect class="' . esc_attr( $class( $series ) ) . '" x="0" y="0" width="' . number_format( max( 0.5, $width ), 2, '.', '' ) . '" height="8" fill="currentColor" />' : '' ) . '</svg>'
				. ( $i > 0 ? '<span class="rooster-admin-funnel__shares">' . ( array() !== $text ? implode( '<span class="rooster-admin-funnel__sep" aria-hidden="true">·</span><span class="screen-reader-text">, </span>', $text ) : '<span class="rooster-admin-funnel__share is-none" aria-hidden="true">—</span>' ) . '</span>' : '' )
				. '</li>';
		}
		$key = $legend && '' !== (string) $series['label'] ? '<ul class="rooster-admin-chart__legend"><li class="' . esc_attr( $class( $series ) ) . '"><span class="rooster-admin-chart__swatch" aria-hidden="true"></span>' . esc_html( (string) $series['label'] ) . '</li></ul>' : '';
		return '<figure class="rooster-admin-chart is-funnel"><ol class="rooster-admin-funnel" aria-label="' . esc_attr( $name ) . '">' . $items . '</ol>' . $key . '</figure>';
	}

	/**
	 * A chart's container (0.75.0, the front application brief; CONTRACT §7): the figure with its configuration as JSON
	 * data and nothing more. The charting library is the consumer's (Rooster One Pro's Highcharts wrapper registers it on
	 * intent or visibility, C7 rules 10 and 13, and draws into the stage), so a page without a chart loads nothing and a
	 * chart below the first screen loads when it is reached. The stage reserves its height from the first paint (nothing
	 * shifts when the chart arrives); the summary under it is what a reader gets before the chart draws and what a
	 * screen reader gets beside it. The inline SVG charts of the admin, drawn with no script, are chart_svg().
	 *
	 * @param string                           $kind   The chart's kind in the consumer's vocabulary (line, column, bar,
	 *                                                 area, pie, donut, spark, treemap …): `is-<kind>` on the figure and
	 *                                                 `kind` in the data; a key.
	 * @param array<int, array<string, mixed>> $series The series as the consumer's wrapper takes them (each a map:
	 *                                                 label, values, tone …), passed through as JSON: scalars and lists,
	 *                                                 nothing else.
	 * @param array<string, mixed>             $opts   label (raw: the chart's accessible name), summary (raw: one
	 *                                                 sentence of what the chart shows), labels (the categories),
	 *                                                 height (sm, md, lg, xl: the stage's reserved height; md), config
	 *                                                 (the rest of the wrapper's configuration: axis titles, formats,
	 *                                                 stacking; JSON as given), id, class, attrs (on the figure).
	 */
	public static function chart( string $kind, array $series, array $opts = array() ): string {
		$kind   = sanitize_key( $kind );
		$kind   = '' !== $kind ? $kind : 'line';
		$height = in_array( $opts['height'] ?? '', array( 'sm', 'md', 'lg', 'xl' ), true ) ? (string) $opts['height'] : 'md';
		$label  = (string) ( $opts['label'] ?? __( 'Chart', 'ai-eshop-optimizer' ) );
		$data   = array(
			'kind'   => $kind,
			'series' => self::json_clean( array_values( $series ) ),
			'labels' => array_values( array_map( 'strval', is_array( $opts['labels'] ?? null ) ? $opts['labels'] : array() ) ),
			'label'  => $label,
			'config' => self::json_clean( is_array( $opts['config'] ?? null ) ? $opts['config'] : array() ),
		);
		$attrs  = array( 'class' => 'rooster-admin-chart is-container is-' . $kind . ' is-h-' . $height . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ) );
		if ( '' !== (string) ( $opts['id'] ?? '' ) ) {
			$attrs['id'] = (string) $opts['id'];
		}
		$attrs['data-ra-chart'] = (string) wp_json_encode( $data );
		$attrs                  = self::merge_attrs( $attrs, $opts['attrs'] ?? null );
		$summary                = (string) ( $opts['summary'] ?? '' );
		return '<figure' . self::attrs( $attrs ) . '><div class="rooster-admin-chart__stage" role="img" aria-label="' . esc_attr( $label ) . '"></div>'
			. ( '' !== $summary ? '<figcaption class="rooster-admin-chart__summary">' . esc_html( $summary ) . '</figcaption>' : '' ) . '</figure>';
	}

	/**
	 * A value as JSON data takes it (chart()): scalars and null as they are, an array with each member cleaned, anything
	 * else (an object, a resource, a closure) dropped.
	 *
	 * @param mixed $value The value.
	 * @return mixed
	 */
	private static function json_clean( $value ) {
		if ( is_array( $value ) ) {
			$out = array();
			foreach ( $value as $key => $item ) {
				if ( is_scalar( $item ) || null === $item || is_array( $item ) ) {
					$out[ $key ] = self::json_clean( $item );
				}
			}
			return $out;
		}
		return is_scalar( $value ) ? $value : null;
	}

	/**
	 * The pin of a card printed without one (escaped; 0.87.0, Registry::anchored()): on a chrome screen, the entry whose
	 * link ends with `#<id>`, as chrome.js's byAnchor() found it after the load before (Rooster One's `aieo-card-…`
	 * cards); '' without an id, off the chrome (no registry, no current product: the storefront's cards) or for none.
	 *
	 * @param string $dom The card's DOM id.
	 */
	private static function anchored_pin( string $dom ): string {
		if ( '' === $dom || ! class_exists( Library::class, false ) ) {
			return '';
		}
		$registry = Library::registry();
		$entry    = null !== $registry && '' !== $registry->current_product() ? $registry->anchored( $dom ) : null;
		return null !== $entry ? Chrome::pin_button( $entry ) : '';
	}

	/**
	 * A card's opening (0.75.0: the one card anatomy, out of rooster_admin_card_open_html(), which resolves a card's
	 * catalogue entry, its section's colour, its pin and its dismissal through the registry and the chrome and prints
	 * through here; on the storefront a screen calls card() itself: no registry, no chrome). The head: the icon, the
	 * title (an h2; h3 for a sub-card), the meta, the tools, the dismiss button, the pin last (H17); then the body, its
	 * description first. Close with card_close(), after card_footer() for a footer; card_section() opens a titled part.
	 *
	 * @param string               $title The title (raw).
	 * @param array<string, mixed> $opts  id (the card's DOM id; its title is `<id>-title`), entry (its catalogue id,
	 *                                    `data-ra-card`), section (the section's class, the chrome's), flush, class,
	 *                                    icon (Lucide), meta (escaped HTML), tools (escaped HTML), dismiss (escaped
	 *                                    HTML: the dismiss button), pin (escaped HTML, '' for none; 0.87.0: unset or
	 *                                    null, on a chrome screen, the pin of the entry whose link ends with `#<id>`), level (3: an h3),
	 *                                    hosted, body_class, attrs (on the section: data-* hooks, a card's place on a
	 *                                    board, `hidden`), description (raw), essential.
	 */
	public static function card_open( string $title, array $opts = array() ): string {
		$dom   = (string) ( $opts['id'] ?? '' );
		$pin   = isset( $opts['pin'] ) ? (string) $opts['pin'] : self::anchored_pin( $dom ); // '' is none; unset or null: its anchor's
		$entry = (string) ( $opts['entry'] ?? '' );
		$class = 'rooster-admin-card' . ( '' !== (string) ( $opts['section'] ?? '' ) ? ' ' . (string) $opts['section'] : '' ) . ( ! empty( $opts['flush'] ) ? ' is-flush' : '' ) . ( isset( $opts['class'] ) && '' !== (string) $opts['class'] ? ' ' . esc_attr( (string) $opts['class'] ) : '' );
		$icon  = (string) ( $opts['icon'] ?? '' );
		$meta  = isset( $opts['meta'] ) && '' !== (string) $opts['meta'] ? '<span class="rooster-admin-card__meta">' . (string) $opts['meta'] . '</span>' : '';
		$tools = isset( $opts['tools'] ) && '' !== (string) $opts['tools'] ? '<div class="rooster-admin-card__tools">' . (string) $opts['tools'] . '</div>' : '';
		$h     = 3 === (int) ( $opts['level'] ?? 2 ) ? 'h3' : 'h2';
		$body  = 'rooster-admin-card__body' . ( ! empty( $opts['hosted'] ) ? ' is-hosted' : '' ) . ( isset( $opts['body_class'] ) && '' !== (string) $opts['body_class'] ? ' ' . (string) $opts['body_class'] : '' );
		$split = self::split_class( $opts['attrs'] ?? null );
		return '<section class="' . esc_attr( $class ) . $split[0] . '"' . ( '' !== $dom ? ' id="' . esc_attr( $dom ) . '" aria-labelledby="' . esc_attr( $dom ) . '-title"' : '' ) . ( '' !== $entry ? ' data-ra-card="' . esc_attr( $entry ) . '"' : '' ) . self::attrs( $split[1] ) . '>'
			. '<header class="rooster-admin-card__head">' . ( '' !== $icon ? Icons::svg( $icon, 18, 'rooster-admin-card__icon' ) : '' ) . '<' . $h . ' class="rooster-admin-card__title"' . ( '' !== $dom ? ' id="' . esc_attr( $dom ) . '-title"' : '' ) . '>' . esc_html( $title ) . '</' . $h . '>' . $meta . $tools . (string) ( $opts['dismiss'] ?? '' ) . $pin . '</header>' // the pin stays last (H17)
			. '<div class="' . esc_attr( $body ) . '">' . ( isset( $opts['description'] ) && '' !== (string) $opts['description'] ? '<p class="rooster-admin-card__desc' . ( ! empty( $opts['essential'] ) ? ' is-essential' : '' ) . '">' . esc_html( (string) $opts['description'] ) . '</p>' : '' );
	}

	/**
	 * A titled section of a card (0.58.0, the Metronic note's F4; rooster_admin_card_section_html()): closes the body
	 * and opens another under a hairline, its h3 title first; card_close() or card_footer() still closes it.
	 *
	 * @param string               $title The section's title (raw; '' for an untitled part).
	 * @param array<string, mixed> $opts  id (the section's anchor, for a deep link), description (raw: one sentence).
	 */
	public static function card_section( string $title = '', array $opts = array() ): string {
		$id = (string) ( $opts['id'] ?? '' );
		return '</div><div class="rooster-admin-card__body is-section"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '"' . ( '' !== $title ? ' role="group" aria-labelledby="' . esc_attr( $id ) . '-title"' : '' ) : '' ) . '>'
			. ( '' !== $title ? '<h3 class="rooster-admin-card__subtitle"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '-title"' : '' ) . '>' . esc_html( $title ) . '</h3>' : '' )
			. ( '' !== (string) ( $opts['description'] ?? '' ) ? '<p class="rooster-admin-card__desc">' . esc_html( (string) $opts['description'] ) . '</p>' : '' );
	}

	/**
	 * Closes a card's body and opens its footer (0.47.0; rooster_admin_card_footer_html()): the actions under a form, a
	 * note about the whole card (`<p class="rooster-admin-card__note">`). card_close() closes the footer as it closes a body.
	 *
	 * 0.85.2 (the LMS's access grid): `sticky` makes it the footer of a long form, shown only while the form differs from
	 * what was saved and then kept at the window's foot while the card is in view: its first line says so (`text`, raw;
	 * `[data-ra-dirty-text]`, a polite status a product's script may reword: "3 unsaved changes"), then the product's
	 * Discard (a reset button of the form) and Save. states.js shows and hides it as it marks the card Unsaved: the form
	 * is a card's form (`form[data-ra-submit]`), or one a product's own script saves (`data-ra-dirty` on the form; after
	 * a save without a reload the script calls roosterAdmin.states.settle( form )).
	 *
	 * @param array<string, mixed> $opts sticky (true), text (raw: the line; "Unsaved changes" by default).
	 */
	public static function card_footer( array $opts = array() ): string {
		if ( empty( $opts['sticky'] ) ) {
			return '</div><div class="rooster-admin-card__footer">';
		}
		$text = (string) ( $opts['text'] ?? __( 'Unsaved changes', 'ai-eshop-optimizer' ) );
		return '</div><div class="rooster-admin-card__footer is-sticky" data-ra-dirty-footer hidden><span class="rooster-admin-card__dirty" role="status" data-ra-dirty-text>' . esc_html( $text ) . '</span>';
	}

	/**
	 * The closing of a card (rooster_admin_card_close_html()).
	 */
	public static function card_close(): string {
		return '</div></section>';
	}

	/**
	 * A fold (0.84.0): a part of a card that opens in place, the browser's details (a guide, a cheat-sheet, the advanced
	 * settings, one connector of several). Its summary is the title, what the operator scans the list for and the
	 * chevron at the end, which turns while the fold is open; the body follows the summary as it came.
	 *
	 * @param string               $title The title (raw).
	 * @param string               $body  The body (escaped HTML).
	 * @param array<string, mixed> $opts  open (true: it starts open), icon (a Lucide name before the title), meta
	 *                                    (escaped HTML after the title: a code, a hint, the facts scanned for), id,
	 *                                    class, attrs (on the details: a data hook, `name` for folds of which one opens).
	 */
	public static function fold( string $title, string $body, array $opts = array() ): string {
		$attrs = array(
			'class' => trim( 'rooster-admin-fold ' . (string) ( $opts['class'] ?? '' ) ),
			'id'    => '' !== (string) ( $opts['id'] ?? '' ) ? (string) $opts['id'] : null,
			'open'  => ! empty( $opts['open'] ),
		);
		$icon  = (string) ( $opts['icon'] ?? '' );
		return '<details' . self::attrs( self::merge_attrs( $attrs, $opts['attrs'] ?? null ) ) . '><summary class="rooster-admin-fold__summary">'
			. ( '' !== $icon ? Icons::svg( $icon, 16 ) : '' ) . '<span>' . esc_html( $title ) . '</span>' . (string) ( $opts['meta'] ?? '' )
			. Icons::svg( 'chevron-right', 16, 'rooster-admin-icon rooster-admin-icon--chevron' ) . '</summary>' . $body . '</details>';
	}

	/**
	 * Someone else's words in a card (0.85.3, the LMS's assignments: a learner's written answer; a customer's message,
	 * a review): a blockquote, set apart by a rule at its start, its paragraphs as written, who said it under it. It is
	 * no help text, so Rules G1 leaves it alone.
	 *
	 * @param string               $text The words (raw; a blank line starts a paragraph).
	 * @param array<string, mixed> $opts html (escaped HTML in place of the text), cite (raw: who, when), id, attrs.
	 */
	public static function quote( string $text, array $opts = array() ): string {
		$body = '' !== (string) ( $opts['html'] ?? '' ) ? (string) $opts['html'] : implode( '', array_map( static fn( string $p ): string => '<p>' . nl2br( esc_html( trim( $p ) ) ) . '</p>', array_filter( (array) preg_split( '/\R\s*\R/', trim( $text ) ), static fn( $p ): bool => '' !== trim( (string) $p ) ) ) );
		$cite = (string) ( $opts['cite'] ?? '' );
		$attrs = self::merge_attrs(
			array(
				'class' => 'rooster-admin-quote',
				'id'    => '' !== (string) ( $opts['id'] ?? '' ) ? (string) $opts['id'] : null,
			),
			$opts['attrs'] ?? null
		);
		return '<blockquote' . self::attrs( $attrs ) . '>' . $body . ( '' !== $cite ? '<footer class="rooster-admin-quote__cite">' . esc_html( $cite ) . '</footer>' : '' ) . '</blockquote>';
	}

	/**
	 * A whole card (0.75.0; CONTRACT §7): card_open(), the body, the footer when given, card_close(). The storefront's
	 * card (the front application brief): no catalogue entry, no pin, no section colour, no dismissal, which are the
	 * registry's and the chrome's (rooster_admin_card() resolves them in the admin and prints through the same anatomy).
	 *
	 * @param string               $title The title (raw).
	 * @param string               $body  The body (escaped HTML).
	 * @param array<string, mixed> $opts  card_open()'s, and footer (escaped HTML), footer_opts (card_footer()'s: sticky, text;
	 *                                    0.85.2).
	 */
	public static function card( string $title, string $body, array $opts = array() ): string {
		$footer = isset( $opts['footer'] ) && '' !== (string) $opts['footer'] ? self::card_footer( is_array( $opts['footer_opts'] ?? null ) ? $opts['footer_opts'] : array() ) . (string) $opts['footer'] : '';
		return self::card_open( $title, $opts ) . $body . $footer . self::card_close();
	}

	/**
	 * An application screen's root on the storefront (0.75.0, front-app.php; CONTRACT §1 "An application page"): the
	 * box the kit's recipes and the theme's tokens apply inside (`rooster-admin rooster-admin-app`, front-app.css), and
	 * the provenance marker every front root carries (C12), `data-rooster-ui="<product>/<screen>"`. The screen's builders
	 * print inside it: a page head of the consumer's own (an h1), cards, a table, tabs; a board or windows only where the
	 * screen asked for their components (rooster_admin_front()'s `board`, `windows`).
	 *
	 * @param string               $ui   `<product>/<screen>` ("om-portal/panel"): the slugs, lower case.
	 * @param string               $body The screen (escaped HTML).
	 * @param array<string, mixed> $opts id, class, attrs (on the root), tag (div; main, section, article).
	 */
	public static function app( string $ui, string $body, array $opts = array() ): string {
		$ui    = strtolower( trim( $ui ) );
		$ui    = 1 === preg_match( '#^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_/-]*$#', $ui ) ? $ui : 'rooster-admin/screen';
		$tag   = in_array( $opts['tag'] ?? '', array( 'main', 'section', 'article' ), true ) ? (string) $opts['tag'] : 'div';
		$attrs = array( 'class' => 'rooster-admin rooster-admin-app' . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . (string) $opts['class'] : '' ) );
		if ( '' !== (string) ( $opts['id'] ?? '' ) ) {
			$attrs['id'] = (string) $opts['id'];
		}
		$attrs['data-rooster-ui'] = $ui;
		$attrs                    = self::merge_attrs( $attrs, $opts['attrs'] ?? null );
		return '<' . $tag . self::attrs( $attrs ) . '>' . $body . '</' . $tag . '>';
	}

	/**
	 * A meter (native `<meter>`; 0.28.0): a measurement within a known range (disk used, a share, a score), which
	 * the browser colours from `low`, `high` and `optimum`; a progress bar is for a task under way.
	 *
	 * @param float                $value The value.
	 * @param array<string, mixed> $opts  min (0), max (100), low, high, optimum, label (raw), value_text (raw: the
	 *                                    text beside the bar and inside the element; default "42 %"), id.
	 */
	public static function meter( float $value, array $opts = array() ): string {
		$min   = (float) ( $opts['min'] ?? 0 );
		$max   = (float) ( $opts['max'] ?? 100 );
		$max   = $max > $min ? $max : $min + 100;
		$value = max( $min, min( $value, $max ) );
		$id    = (string) ( $opts['id'] ?? '' );
		$label = (string) ( $opts['label'] ?? '' );
		$text  = (string) ( $opts['value_text'] ?? ( (string) (int) round( 100 * ( $value - $min ) / ( $max - $min ) ) . ' %' ) );
		$attrs = array(
			'class' => 'rooster-admin-meter__bar',
			'value' => (string) $value,
			'min'   => (string) $min,
			'max'   => (string) $max,
		);
		foreach ( array( 'low', 'high', 'optimum' ) as $key ) {
			if ( isset( $opts[ $key ] ) ) {
				$attrs[ $key ] = (string) (float) $opts[ $key ];
			}
		}
		if ( '' !== $id ) {
			$attrs['id'] = $id;
			if ( '' !== $label ) {
				$attrs['aria-labelledby'] = $id . '-label';
			}
		}
		return '<span class="rooster-admin-meter">'
			. ( '' !== $label ? '<span class="rooster-admin-meter__label"' . ( '' !== $id ? ' id="' . esc_attr( $id ) . '-label"' : '' ) . '>' . esc_html( $label ) . '</span>' : '' )
			. '<meter' . self::attrs( $attrs ) . '>' . esc_html( $text ) . '</meter>'
			. '<span class="rooster-admin-meter__value">' . esc_html( $text ) . '</span></span>';
	}

	/**
	 * A wizard (0.28.0): the steps indicator, one panel per step (the others hidden and inert), Back and Next. The
	 * script moves between the panels, keeps the indicator, focuses the panel's first control, announces
	 * `rooster-admin:wizard` ({step, last}) on each move and `rooster-admin:finish` on the last step's button, which
	 * submits the enclosing form when `submit` is set.
	 *
	 * @param string                           $id      The element id.
	 * @param array<int, array<string, mixed>> $steps   {label (raw), body (escaped HTML)}.
	 * @param int                              $current The current step (1-based).
	 * @param array<string, mixed>             $opts    back, next, finish (the labels), submit (true: the last step's
	 *                                                  button submits the form), label (the indicator's name).
	 */
	public static function wizard( string $id, array $steps, int $current, array $opts = array() ): string {
		$count   = count( $steps );
		$current = max( 1, min( $current, max( 1, $count ) ) );
		$next    = (string) ( $opts['next'] ?? __( 'Next', 'ai-eshop-optimizer' ) );
		$finish  = (string) ( $opts['finish'] ?? __( 'Finish', 'ai-eshop-optimizer' ) );
		$labels  = array();
		foreach ( $steps as $step ) {
			$labels[] = (string) ( $step['label'] ?? '' );
		}
		$html = '<div' . self::attrs(
			array(
				'class'                 => 'rooster-admin-wizard',
				'id'                    => $id,
				'data-ra-wizard'        => (string) $current,
				'data-ra-wizard-next'   => $next,
				'data-ra-wizard-finish' => $finish,
				'data-ra-wizard-submit' => ! empty( $opts['submit'] ) ? '' : null,
			)
		) . '>' . self::steps( $labels, $current, array( 'label' => (string) ( $opts['label'] ?? __( 'Steps', 'ai-eshop-optimizer' ) ) ) ) . '<div class="rooster-admin-wizard__panels">';
		$n    = 0;
		foreach ( $steps as $step ) {
			++$n;
			/* translators: 1: the step's number, 2: its label. */
			$name  = sprintf( __( 'Step %1$d: %2$s', 'ai-eshop-optimizer' ), $n, (string) ( $step['label'] ?? '' ) );
			$html .= '<section class="rooster-admin-wizard__panel" data-ra-wizard-panel="' . $n . '" aria-label="' . esc_attr( $name ) . '"' . ( $n === $current ? '' : ' hidden inert' ) . '>' . (string) ( $step['body'] ?? '' ) . '</section>';
		}
		$last  = $current === $count;
		$html .= '</div><div class="rooster-admin-actions rooster-admin-wizard__actions">'
			. self::button( (string) ( $opts['back'] ?? __( 'Back', 'ai-eshop-optimizer' ) ), array( 'disabled' => 1 === $current, 'attrs' => array( 'data-ra-wizard-back' => '' ) ) )
			. self::button( $last ? $finish : $next, array( 'variant' => 'primary', 'type' => $last && ! empty( $opts['submit'] ) ? 'submit' : 'button', 'attrs' => array( 'data-ra-wizard-next' => '' ) ) )
			. '</div></div>';
		return $html;
	}
}