<?php
/**
 * Helper functions for third-party plugins to filter Sifency Elementor widgets.
 *
 * @package Sifency_Addons
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Exclude entire widget categories from registration and admin lists.
 *
 * @param string[] $categories Category keys as defined in sifency-widgets.php (e.g. 'Typography', 'WooCommerce').
 * @param int      $priority   Filter priority.
 */
function sifency_addons_exclude_widget_categories( array $categories, int $priority = 10 ): void {
	add_filter(
		'sifency_addons_excluded_widget_categories',
		static function ( $excluded ) use ( $categories ) {
			$excluded   = is_array( $excluded ) ? $excluded : array();
			$categories = array_map( 'strval', $categories );

			return array_values( array_unique( array_merge( $excluded, $categories ) ) );
		},
		$priority
	);
}

/**
 * Exclude individual widgets by registry ID from registration and admin lists.
 *
 * @param string[] $widget_ids Widget keys (e.g. 'sifency-addons-marquee', 'sifency-data-table').
 * @param int      $priority   Filter priority.
 */
function sifency_addons_exclude_widgets( array $widget_ids, int $priority = 10 ): void {
	add_filter(
		'sifency_addons_excluded_widgets',
		static function ( $excluded ) use ( $widget_ids ) {
			$excluded   = is_array( $excluded ) ? $excluded : array();
			$widget_ids = array_map( 'strval', $widget_ids );

			return array_values( array_unique( array_merge( $excluded, $widget_ids ) ) );
		},
		$priority
	);
}

/**
 * Add or merge widgets into a category via sifency_addons_widget_list.
 *
 * @param string                              $category Category name (created if missing).
 * @param array<string, array<string, mixed>> $widgets  Widget ID => config (title, class, file, icon, …).
 * @param int                                 $priority Filter priority.
 */
function sifency_addons_register_widgets( string $category, array $widgets, int $priority = 10 ): void {
	add_filter(
		'sifency_addons_widget_list',
		static function ( $categorized ) use ( $category, $widgets ) {
			if ( ! is_array( $categorized ) ) {
				$categorized = array();
			}

			if ( ! isset( $categorized[ $category ] ) || ! is_array( $categorized[ $category ] ) ) {
				$categorized[ $category ] = array();
			}

			foreach ( $widgets as $widget_id => $widget_data ) {
				if ( is_array( $widget_data ) ) {
					$categorized[ $category ][ $widget_id ] = $widget_data;
				}
			}

			return $categorized;
		},
		$priority
	);
}

/**
 * Prevent specific widgets from being registered with Elementor (runtime gate).
 *
 * @param string[] $widget_ids Widget registry keys to block.
 * @param int      $priority   Filter priority.
 */
function sifency_addons_block_widget_registration( array $widget_ids, int $priority = 10 ): void {
	$blocked = array_flip( array_map( 'strval', $widget_ids ) );

	add_filter(
		'sifency_addons_register_widget',
		static function ( $register, $widget_id ) use ( $blocked ) {
			if ( isset( $blocked[ (string) $widget_id ] ) ) {
				return false;
			}

			return $register;
		},
		$priority,
		2
	);
}
