<?php
/**
 * Trait mirroring Pro-owned settings fields into a free_with_pro_options
 * module's own settings page when Pro is active. See ARCHITECTURE_V3.md
 * Section 13.1.
 *
 * @package admin-optimizer
 */

namespace Yipresser\AdminOptimizer\Modules;

use Yipresser\AdminOptimizer\Module_Registry;

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

/**
 * Shared behavior for settings classes that ship pro-gated fields in the
 * free plugin: where those fields render, and how their values survive a
 * save made while Pro is inactive.
 */
trait Pro_Settings {

	/**
	 * Option keys that only Pro's UI ever writes. The free form has no
	 * control for these, so sanitize_settings() must not drop them just
	 * because Pro is inactive during a given save.
	 *
	 * @return string[]
	 */
	abstract protected function get_pro_only_option_keys(): array;

	/**
	 * Whether the Pro plugin is active. Thin wrapper so a consuming class
	 * can stub this in tests.
	 *
	 * @return bool
	 */
	protected function is_pro_active(): bool {
		return Module_Registry::is_pro_active();
	}

	/**
	 * Append pro field definitions to an already-registered section (one
	 * whose menu_slug is the module's real, submitted option page) instead
	 * of registering a second, non-submitting decorative form. Call only
	 * when is_pro_active() is true.
	 *
	 * @param array  $sections   Sections array as built in init().
	 * @param string $section_id Target section's 'id'.
	 * @param array  $pro_fields Field defs to add (already un-disabled).
	 *
	 * @return array
	 */
	protected function inject_pro_fields( array $sections, string $section_id, array $pro_fields ): array {
		foreach ( $sections as &$section ) {
			if ( ( $section['id'] ?? null ) === $section_id ) {
				$section['fields'] = array_merge( $section['fields'] ?? [], $pro_fields );
				break;
			}
		}
		unset( $section );
		return $sections;
	}

	/**
	 * Swap one field definition for another within a section, in place —
	 * for fields whose name is shared between the free and Pro settings
	 * classes but whose type/semantics differ between the two.
	 *
	 * @param array  $sections   Sections array as built in init().
	 * @param string $section_id Target section's 'id'.
	 * @param string $field_id   The existing field's 'id' to replace.
	 * @param array  $new_field  Replacement field def.
	 *
	 * @return array
	 */
	protected function replace_field( array $sections, string $section_id, string $field_id, array $new_field ): array {
		foreach ( $sections as &$section ) {
			if ( ( $section['id'] ?? null ) !== $section_id ) {
				continue;
			}
			foreach ( $section['fields'] as &$field ) {
				if ( ( $field['id'] ?? null ) === $field_id ) {
					$field = $new_field;
					break 2;
				}
			}
		}
		unset( $section, $field );
		return $sections;
	}

	/**
	 * Safety net for sanitize_settings(): re-seed pro-only keys from the
	 * previously stored option when Pro is inactive, so a free-mode save
	 * doesn't silently erase values Pro wrote earlier.
	 *
	 * @param array $sanitized_options Result built so far by the module's own sanitize logic.
	 *
	 * @return array
	 */
	protected function carry_forward_inactive_pro_keys( array $sanitized_options ): array {
		if ( $this->is_pro_active() ) {
			return $sanitized_options;
		}
		foreach ( $this->get_pro_only_option_keys() as $key ) {
			if ( ! isset( $sanitized_options[ $key ] ) && isset( $this->options[ $key ] ) ) {
				$sanitized_options[ $key ] = $this->options[ $key ];
			}
		}
		return $sanitized_options;
	}
}