<?php
/**
 * Front-end design tokens.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Support;

defined( 'ABSPATH' ) || exit;

/**
 * The colours, corners and spacing every front-end control of this plugin — and
 * of any add-on — reads from.
 *
 * ## Why this exists
 *
 * Each widget used to carry its own palette: the login panel, the Jalali date
 * picker, the city autocomplete, the add-on's back-in-stock dialog. Four
 * stylesheets, four opinions, and no way for a shop to change any of them
 * without fighting specificity. Worse, three of them tried to be helpful by
 * answering `prefers-color-scheme`, which reports the *visitor's operating
 * system* — so a shop with a light theme, opened on a machine set to dark, got
 * a black dialog in the middle of a white page.
 *
 * A storefront's colours are decided by its theme and its owner. Never by the
 * visitor's device. That is the whole argument for this class, and it is why
 * there is no "automatic" scheme here and must not be one.
 *
 * ## How it reaches the page
 *
 * Not through `wp_head`. Several of these controls are enqueued from inside
 * their own render — the stock dialog is printed in the middle of the body on
 * out-of-stock products only — so a `wp_head` hook would be too early for some
 * and pure waste on the many pages that show none of them.
 *
 * Instead the declarations ride along with whichever stylesheet is loaded, via
 * {@see self::attach()}. A page with no Rahkar control on it pays nothing at
 * all, and the add-on gets the same values by calling the same method.
 *
 * Custom properties resolve at computed-value time rather than in parse order,
 * so it does not matter which of our stylesheets the block lands on.
 */
final class Tokens {

	/**
	 * Settings slug. Not a module: appearance has no on/off switch.
	 *
	 * @see \Rahkar\WP\Admin\AppearanceSettings
	 */
	public const SLUG = 'appearance';

	/**
	 * Follow the shop's own palette where the theme publishes one.
	 */
	public const SCHEME_THEME = 'theme';

	public const SCHEME_LIGHT = 'light';
	public const SCHEME_DARK  = 'dark';

	/**
	 * The light palette, and the shipped defaults for everything else.
	 *
	 * Also the fallback for every other scheme: the theme scheme resolves each
	 * value against these, so a theme that publishes nothing lands here rather
	 * than on an unstyled control.
	 *
	 * @var array<string, string>
	 */
	private const LIGHT = [
		'surface'    => '#ffffff',
		'surface-2'  => '#f6f7f8',
		'ink'        => '#1f2024',
		'muted'      => '#6b6b6b',
		'border'     => '#d6d6d6',
		'accent'     => '#1e874b',
		'accent-ink' => '#ffffff',
	];

	/**
	 * The dark palette.
	 *
	 * For a shop whose theme is dark. Chosen by the shop owner on the settings
	 * screen, never detected.
	 *
	 * @var array<string, string>
	 */
	private const DARK = [
		'surface'    => '#1c1e22',
		'surface-2'  => '#26282d',
		'ink'        => '#f1f2f4',
		'muted'      => '#a7abb3',
		'border'     => '#3a3d44',
		'accent'     => '#3fae6d',
		'accent-ink' => '#0d1f15',
	];

	/**
	 * Theme-published custom properties, per token.
	 *
	 * Block themes publish their `theme.json` palette as `--wp--preset--color--*`,
	 * which is the one naming convention that is actually standard rather than
	 * guessed. `base` and `contrast` are the two every default theme defines.
	 *
	 * A token with no entry here has no standard source, so it keeps the light
	 * value. Better a known colour than a guess at a variable that may mean
	 * something else entirely in the theme that defined it.
	 *
	 * @var array<string, string>
	 */
	private const THEME_VARS = [
		'surface'    => '--wp--preset--color--base',
		'ink'        => '--wp--preset--color--contrast',
		'accent'     => '--wp--preset--color--primary',
		'accent-ink' => '--wp--preset--color--base',
	];

	/**
	 * Tokens a shop may override by hand, and the state tokens it may not.
	 *
	 * The state colours are deliberately not configurable: an error that is not
	 * red and a success that is not green cost more in confusion than they gain
	 * in brand fidelity.
	 *
	 * @var array<string, string>
	 */
	private const STATES = [
		'error'   => '#c0392b',
		'success' => '#1e874b',
		'notice'  => '#8a6d1f',
	];

	/**
	 * Shipped values for the non-colour tokens.
	 */
	private const RADIUS = 6;
	private const GAP    = '0.75rem';

	/**
	 * The rendered block, built at most once per request.
	 *
	 * @var string|null
	 */
	private static ?string $css = null;

	/**
	 * Whether the block has already been attached to a stylesheet.
	 *
	 * @var bool
	 */
	private static bool $attached = false;

	/**
	 * Ship the tokens alongside a stylesheet of ours.
	 *
	 * Called straight after `wp_enqueue_style()` by whatever enqueued it. Only
	 * the first caller in a request actually attaches anything; the rest are
	 * no-ops, because one `:root` block serves every control on the page.
	 *
	 * @param string $handle The stylesheet handle just enqueued.
	 */
	public static function attach( string $handle ): void {
		if ( self::$attached ) {
			return;
		}

		self::$attached = true;

		// Every value is validated in safeValue(); stripping tags as well keeps
		// the output safe at the point it is written, whatever feeds the block.
		wp_add_inline_style( $handle, wp_strip_all_tags( self::css() ) );
	}

	/**
	 * The `:root` block.
	 *
	 * Public so the settings screen can show the shop owner exactly what their
	 * choices produce, rather than describing it.
	 */
	public static function css(): string {
		if ( null !== self::$css ) {
			return self::$css;
		}

		$declarations = '';

		foreach ( self::resolve() as $name => $value ) {
			$declarations .= sprintf( '--rahkar-%s:%s;', $name, $value );
		}

		self::$css = ':root{' . $declarations . '}';

		return self::$css;
	}

	/**
	 * Every token with its final value.
	 *
	 * @return array<string, string>
	 */
	public static function resolve(): array {
		$settings = Settings::all( self::SLUG );
		$scheme   = (string) ( $settings['scheme'] ?? self::SCHEME_LIGHT );

		$base = self::SCHEME_DARK === $scheme ? self::DARK : self::LIGHT;

		$tokens = [];

		foreach ( self::LIGHT as $name => $light ) {
			// Indexed without a fallback on purpose: the two palettes must carry
			// the same keys, and static analysis says so at build time rather than
			// letting a half-added token quietly resolve to the light value in a
			// dark shop.
			$value = $base[ $name ];

			// The theme scheme wraps each value in `var()` with our own colour as
			// the fallback, so it degrades by itself: a theme that publishes the
			// property wins, and a theme that does not is simply light. That is
			// what makes this a setting a shop owner can safely pick without
			// knowing anything about how their theme is built.
			if ( self::SCHEME_THEME === $scheme && isset( self::THEME_VARS[ $name ] ) ) {
				$value = sprintf( 'var(%s,%s)', self::THEME_VARS[ $name ], $value );
			}

			$tokens[ $name ] = $value;
		}

		// A hand-written override beats everything, including the theme scheme:
		// it is the escape hatch for classic themes, which publish no standard
		// palette but do publish their own variables.
		foreach ( [ 'surface', 'ink', 'accent' ] as $name ) {
			$override = self::safeValue( (string) ( $settings[ $name . '_override' ] ?? '' ) );

			if ( '' !== $override ) {
				$tokens[ $name ] = $override;
			}
		}

		$radius = (int) ( $settings['radius'] ?? self::RADIUS );

		$tokens['radius'] = max( 0, min( 32, $radius ) ) . 'px';
		$tokens['gap']    = self::GAP;

		return array_merge( $tokens, self::STATES );
	}

	/**
	 * Accept a hand-written value, or nothing.
	 *
	 * This ends up inside a `<style>` block, so it is validated rather than
	 * escaped: `#fff;}body{display:none` is a perfectly good escaped string and
	 * a perfectly good way to take a shop's front page down. Only the shapes a
	 * colour can legitimately take are allowed through, and anything else — a
	 * typo included — is dropped in favour of the scheme's value.
	 *
	 * @param string $raw Value as typed on the settings screen.
	 */
	public static function safeValue( string $raw ): string {
		$value = trim( $raw );

		if ( '' === $value ) {
			return '';
		}

		// #rgb, #rrggbb, #rrggbbaa
		if ( preg_match( '/^#[0-9a-f]{3,8}$/i', $value ) ) {
			return $value;
		}

		// rgb()/rgba()/hsl()/hsla(), digits, separators and percent only.
		if ( preg_match( '/^(rgba?|hsla?)\(\s*[0-9a-z%.,\/\s+-]{1,60}\)$/i', $value ) ) {
			return $value;
		}

		// var(--name) or var(--name, #fallback). One level: a nested fallback is
		// where the grammar gets loose enough to be worth refusing.
		if ( preg_match( '/^var\(\s*--[a-z0-9_-]{1,64}\s*(,\s*[#a-z0-9%.()\s,\/-]{1,60})?\)$/i', $value ) ) {
			return $value;
		}

		// A bare colour keyword: white, transparent, currentColor.
		if ( preg_match( '/^[a-z]{3,20}$/i', $value ) ) {
			return $value;
		}

		return '';
	}

	/**
	 * Forget the built block.
	 *
	 * For the settings screen, which renders the preview in the same request that
	 * saved new values.
	 */
	public static function flush(): void {
		self::$css = null;
	}
}