<?php
/**
 * Divi 5 documentation URLs for settings dashboard cards.
 *
 * Slugs verified against https://docs.divisupreme.com/divi-5/ nav (VitePress).
 *
 * @package DiviSupreme
 */

declare(strict_types=1);

namespace DiviSupreme\Core;

/**
 * Maps settings dashboard module / extension keys to docs.divisupreme.com/divi-5 paths.
 */
final class DocumentationUrls {

	public const DIVI_5_BASE = 'https://docs.divisupreme.com/divi-5';

	/**
	 * Module setting keys (`dsm_modules`) → docs path slug under `/divi-5/modules/`.
	 * Value `null` = no dedicated page yet (falls back to modules index).
	 *
	 * @var array<string, string|null>
	 */
	private const MODULE_DOC_SLUGS = array(
		'AdvancedTabs'              => 'advanced-tabs',
		'AnimatedGradientText'      => 'animated-gradient-text',
		'AnimatedHeadline'          => 'animated-headline',
		'Badges'                    => 'text-badges',
		'BeforeAfterImage'          => 'before-after-slider',
		'BlobImage'                 => 'blob-image',
		'BlockRevealImage'          => 'block-reveal-image',
		'BlockRevealText'           => 'block-reveal-text',
		'BlogCarousel'              => 'blog-carousel',
		'Breadcrumbs'               => 'breadcrumbs',
		'BusinessHours'             => 'business-hours',
		'Buttons'                   => 'buttons',
		'Card'                      => 'card',
		'CardCarousel'              => 'card-carousel',
		'CircleInfo'                => 'circle-info',
		'ContactForm7'              => 'contact-form7',
		'ContentTimeLine'           => 'content-timeline',
		'ContentToggle'             => 'content-toggle',
		'DualHeading'               => 'dual-heading',
		'EmbedGoogleMap'            => 'embed-google-map',
		'EmbedTwitterTimeline'      => null,
		'FacebookEmbed'             => 'facebook-embed',
		'FacebookLikeButton'        => null,
		'FacebookSimpleComments'    => null,
		'FacebookSimpleFeed'        => 'facebook-simple-feed',
		'Faq'                       => 'faq',
		'FilterableGallery'         => 'filterable-gallery',
		'FlipBoxPerk'               => 'flipbox-perk',
		'FloatingMultiImages'       => 'floating-multi-images',
		'GlitchText'                => 'glitch-text',
		'GradientText'              => 'gradient-text',
		'IconDivider'               => 'icon-divider',
		'IconList'                  => 'icon-list',
		'ImageAccordion'            => 'image-accordion',
		'ImageCarousel'             => 'image-carousel',
		'ImageHotSpots'             => 'image-hotspots',
		'ImageHoverReveal'          => 'image-hover-reveal',
		'ImageReveal'               => 'image-reveal',
		'LineHover'                 => 'line-hover',
		'Lottie'                    => 'lottie',
		'MaskText'                  => 'mask-text',
		'MasonryGallery'            => 'masonry-gallery',
		'Menu'                      => 'menu',
		'OnScrollHeaderAnimation'   => 'on-scroll-header-animation',
		'PerspectiveImage'          => 'perspective-image',
		'PostCarousel'              => 'post-carousel',
		'PriceList'                 => 'price-list',
		'ProgressBar'               => 'progress-bar',
		'RandomImage'               => 'random-image',
		'Readmore'                  => 'readmore',
		'ScrollImage'               => 'scroll-image',
		'Shapes'                    => 'shapes',
		'ShuffleLetters'            => 'shuffle-letters',
		'SocialShareButtons'        => 'social-share-buttons',
		'StackingCard'              => 'stacking-card',
		'StarRating'                => 'star-rating',
		'StepFlow'                  => 'step-flow',
		'SvgAnimation'              => 'svg-animation',
		'TableOfContents'           => 'table-of-contents',
		'TextDivider'               => 'text-divider',
		'TextNotation'              => 'text-notation',
		'TextPath'                  => 'text-path',
		'TextRotator'               => 'text-rotator',
		'TiltImage'                 => 'tilt-image',
		'TypingEffect'              => 'typing-effect',
	);

	/**
	 * General-tab extension toggles (`dsm_general` keys) → slug under `/divi-5/extensions/`.
	 *
	 * @var array<string, string>
	 */
	private const EXTENSION_DOC_SLUGS = array(
		'dsm_use_supreme_popup'         => 'divi-popup',
		'dsm_use_line_hover_animation'  => 'line-hover-animation',
		'dsm_use_supreme_parallax'      => 'mouse-parallax',
		'dsm_use_image_parallax'        => 'image-parallax',
		'dsm_use_custom_cursor'         => 'custom-cursor',
		'dsm_use_icon_libraries'        => 'icon-libraries',
		'dsm_use_mask_pattern_library'  => 'mask-pattern-library',
		'dsm_use_library_widget'        => 'divi-library-widget',
	);

	/**
	 * @param string $setting_key Module registry / `dsm_modules` key (e.g. `BlogCarousel`).
	 */
	public static function module_doc_url( string $setting_key ): string {
		$slug = self::MODULE_DOC_SLUGS[ $setting_key ] ?? null;

		if ( null === $slug || '' === $slug ) {
			return self::DIVI_5_BASE . '/modules/';
		}

		return self::DIVI_5_BASE . '/modules/' . $slug;
	}

	/**
	 * @param string $setting_name General-tab extension option name (e.g. `dsm_use_supreme_popup`).
	 */
	public static function extension_doc_url( string $setting_name ): string {
		$slug = self::EXTENSION_DOC_SLUGS[ $setting_name ] ?? '';

		if ( '' === $slug ) {
			return self::DIVI_5_BASE . '/extensions/';
		}

		return self::DIVI_5_BASE . '/extensions/' . $slug;
	}

	/**
	 * Icon Libraries extension doc (per-library cards share the same extension guide).
	 */
	public static function icon_libraries_doc_url(): string {
		return self::extension_doc_url( 'dsm_use_icon_libraries' );
	}

	/**
	 * @return array<int, string> Setting keys with no dedicated module doc page.
	 */
	public static function module_keys_without_dedicated_doc(): array {
		$missing = array();

		foreach ( self::MODULE_DOC_SLUGS as $key => $slug ) {
			if ( null === $slug ) {
				$missing[] = $key;
			}
		}

		return $missing;
	}
}
