<?php
/**
 * Persian province labels for WooCommerce.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Modules\IranLocations;

defined( 'ABSPATH' ) || exit;

/**
 * Replaces WooCommerce's transliterated Iranian province names.
 *
 * This lives apart from {@see CheckoutFields} for one measured reason: the
 * `woocommerce_states` filter fires on ordinary pages, not just checkout — the
 * homepage and shop archive both reach it. Hanging it off the checkout class
 * meant that class, and the address-field machinery it carries, loaded on every
 * page of the store. This file exists to keep that cost to one small class.
 *
 * The state **codes are never touched**. Orders already in the database,
 * shipping zone rules, tax rules, and every CSV export key off `THR`, `ESF`, and
 * the rest; redefining them would break all of it silently. Only what the
 * customer reads changes.
 */
final class ProvinceLabels {

	/**
	 * Swap in the Persian-only labels.
	 *
	 * @param array<string, array<string, string>> $states All states by country.
	 *
	 * @return array<string, array<string, string>>
	 *
	 * @internal Hooked callback.
	 */
	public function filter( array $states ): array {
		$provinces = LocationRepository::provinces();

		if ( [] === $provinces ) {
			return $states;
		}

		// `array_replace` rather than assignment: if a future WooCommerce release
		// adds a province our dataset predates, keeping its English label beats
		// dropping the province entirely.
		$states['IR'] = array_replace( $states['IR'] ?? [], $provinces );

		return $states;
	}
}