<?php
/**
 * Help link registry.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Where each section's "?" leads.
 *
 * One page per section, not per field: a module and every screen that belongs
 * to it share one page — the notifications settings, the gateways screen and
 * the notification editor all open the notifications guide. The same scheme as
 * the PrestaShop modules' `config/docs.php`, and like that file this list is
 * the complete set of pages rahkarnet.com must provide for this plugin.
 */
final class Help {

	/**
	 * Where the guides live.
	 */
	private const BASE_URL = 'https://rahkarnet.com/doc/';

	/**
	 * Section key => page slug. Module slugs are keys too.
	 *
	 * @var array<string, string>
	 */
	private const SLUGS = [
		'overview'       => 'wp-overview',
		'modules'        => 'wp-modules',
		'settings'       => 'wp-settings',
		'health'         => 'wp-health',
		'logs'           => 'wp-logs',
		'pro'            => 'wp-pro',
		'iran_locations' => 'wp-iran-locations',
		'notifications'  => 'wp-notifications',
		'otp_auth'       => 'wp-sms-login',
		'order_print'    => 'wp-order-print',
		'jalali'         => 'wp-jalali',
		'courier_status' => 'wp-courier-status',
		'order_tracking' => 'wp-order-tracking',
		'testimonials'   => 'wp-testimonials',
	];

	/**
	 * The guide for one section.
	 *
	 * A key this list does not know — an add-on's module — gets `wp-` and its
	 * slug with dashes, so a new module has a help link from day one; the
	 * add-on can point it elsewhere through the filter.
	 *
	 * @param string $key Section key or module slug.
	 */
	public static function url( string $key ): string {
		$slug = self::SLUGS[ $key ] ?? 'wp-' . str_replace( '_', '-', sanitize_key( $key ) );

		/**
		 * Filters a section's help page.
		 *
		 * @param string $url Full URL of the guide.
		 * @param string $key Section key or module slug.
		 */
		$url = (string) apply_filters( 'rahkar_wp_help_url', self::BASE_URL . $slug, $key );

		// Tells rahkarnet.com's analytics which screen the click came from.
		return add_query_arg(
			[
				'utm_source'   => 'rahkar-toolkit',
				'utm_medium'   => 'plugin',
				'utm_campaign' => 'help',
				'utm_content'  => sanitize_key( $key ),
			],
			$url
		);
	}

	/**
	 * The "?" button for one section.
	 *
	 * @param string $key   Section key or module slug.
	 * @param string $topic What the guide explains, for the tooltip.
	 */
	public static function link( string $key, string $topic ): string {
		return Ui::help( self::url( $key ), $topic );
	}
}