<?php
/**
 * Attr normalization for `divi_module_library_register_module_attrs` hooks in {@see DiviSupreme\Modules}.
 *
 * Module classes depend on this class — not on {@see DiviSupreme\Includes\Divi5Conversion} — so
 * conversion/migrator code stays isolated under Divi5Conversion/.
 *
 * @package DiviSupreme
 */

declare(strict_types=1);

namespace DiviSupreme\Includes;

use DiviSupreme\Includes\Divi5Conversion\ConversionAttrs;

/**
 * Delegates to ConversionAttrs for register-module merge normalization.
 */
final class ModuleRegisterAttrsNormalize {

	/**
	 * Random Image: coerce overlay toggles after merged attrs (legacy bool / string shapes).
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function random_image_overlay_toggles( array &$attrs ): void {
		ConversionAttrs::coerce_inner_desktop_toggle_on_off( $attrs, 'use_overlay', 'off' );
		ConversionAttrs::coerce_inner_desktop_toggle_on_off( $attrs, 'overlay_on_hover', 'on' );
	}

	/**
	 * Scroll Image: normalize uploads, decoration title, toggles, ranges after merge.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function scroll_image_merged( array &$attrs ): void {
		ConversionAttrs::normalize_scroll_image_merged_attrs( $attrs );
	}

	/**
	 * Perspective Image: uploads + alt/title → Advanced → Attributes (scroll-image pattern).
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function perspective_image_merged( array &$attrs ): void {
		ConversionAttrs::normalize_perspective_image_merged_attrs( $attrs );
	}

	/**
	 * Dual Heading: display types, heading tag, legacy parts_gap, range normalization.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function dual_heading_merged( array &$attrs ): void {
		ConversionAttrs::normalize_dual_heading_attrs( $attrs );
	}

	/**
	 * Card Carousel Child: ensure rich `content` uses `{ text }` under `innerContent.*.value` for Visual Builder.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function card_carousel_child_merged( array &$attrs ): void {
		ConversionAttrs::normalize_flipbox_rich_content_inner_content_for_vb( $attrs, 'content' );
	}

	/**
	 * Image Hotspots Child: ensure rich `content` uses `{ text }` under `innerContent.*.value` for Visual Builder.
	 *
	 * D4→D5 migration often stores tooltip HTML as a **string** at `*.value`; VB RichText expects `*.value.text`.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function image_hotspots_child_merged( array &$attrs ): void {
		ConversionAttrs::normalize_flipbox_rich_content_inner_content_for_vb( $attrs, 'content' );
	}

	/**
	 * Typing Effect: coerce pipe / JSON string / legacy shapes to SortableList rows for Visual Builder.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function typing_effect_merged( array &$attrs ): void {
		ConversionAttrs::normalize_typing_effect_block_attrs( $attrs );
	}

	/**
	 * FAQ parent: migrate legacy toggle row color `innerContent` into `decoration.background`.
	 *
	 * @param array<string, mixed> $attrs Module attrs by reference.
	 * @return void
	 */
	public static function faq_merged( array &$attrs ): void {
		ConversionAttrs::migrate_faq_toggle_legacy_inner_content_color_into_decoration_background( $attrs );
	}

	/**
	 * FAQ child item: migrate legacy toggle row color; copy from parent FAQ when child never set its own row backgrounds.
	 *
	 * @param array<string, mixed>      $attrs         Child module attrs reference.
	 * @param array<string, mixed>|null $parent_attrs Parent `dsm/faq` attrs (optional).
	 * @return void
	 */
	public static function faq_child_merged( array &$attrs, ?array $parent_attrs = null ): void {
		ConversionAttrs::migrate_faq_toggle_legacy_inner_content_color_into_decoration_background( $attrs );

		if ( \is_array( $parent_attrs ) && array() !== $parent_attrs ) {
			ConversionAttrs::hydrate_faq_child_toggle_backgrounds_from_parent( $attrs, $parent_attrs );
		}
	}
}
