<?php
/**
 * CommonWidgetFields trait — single seat-belt for shared widget form/update.
 *
 * Every AKSRT widget `use`s this trait so the Zibll common-field family
 * (title block, display rules, affix, animation, layout bg) is declared and
 * persisted in exactly one place: inc/modules/widget-common.php.
 *
 * Widgets keep only their business fields; the trait wires the shared section
 * into form() and folds the shared keys into update().
 *
 * @package AKSRT\Widgets\Traits
 */

namespace AKSRT\Widgets\Traits;

defined('ABSPATH') || exit;

trait CommonWidgetFields {

	/**
	 * Whether this widget should render the shared common-form section.
	 *
	 * Override and return false for pure-display widgets with no admin form.
	 * Default: true (every widget gets the shared block).
	 *
	 * @return bool
	 */
	protected function use_common_form(): bool {
		return true;
	}

	/**
	 * Render the shared common-form section at the end of a widget's form().
	 *
	 * Call from form(): render business fields, then `$this->render_common_form_section($instance);`.
	 *
	 * @param array<string,mixed> $instance Widget instance.
	 */
	protected function render_common_form_section(array $instance): void {
		if (!$this->use_common_form()) {
			return;
		}
		if (function_exists('aksrt_widget_render_common_form')) {
			aksrt_widget_render_common_form($instance);
		}
	}

	/**
	 * Merge shared common fields into a widget's update() result.
	 *
	 * Usage in update():
	 *   return $this->update_common_fields($new_instance, $old_instance, [
	 *       'title' => sanitize_text_field(...),
	 *       ...business fields...
	 *   ]);
	 *
	 * @param array<string,mixed> $new_instance New submitted instance.
	 * @param array<string,mixed> $old_instance Previous instance.
	 * @param array<string,mixed> $business     Sanitized business fields to keep.
	 * @return array<string,mixed>
	 */
	protected function update_common_fields(array $new_instance, array $old_instance, array $business = []): array {
		if (!$this->use_common_form()) {
			return $business;
		}
		if (function_exists('aksrt_widget_update_common')) {
			$common = aksrt_widget_update_common($new_instance, $old_instance);
			return array_merge($business, $common);
		}
		return $business;
	}
}