<?php
/**
 * Elio Blocks public API: registration functions for providers and condition
 * icons, called on the elio_blocks_init action, and the functions the
 * render.php of the blocks read what they print with.
 *
 * @package ElioBlocks
 */

use ElioBlocks\Plugin;
use ElioBlocks\Provider\Provider;
use ElioBlocks\Provider\ProviderRegistry;
use ElioBlocks\Interactivity\Blocks\Report\DirectivesHelper;
use ElioBlocks\Interactivity\Blocks\Report\IconSprite;
use ElioBlocks\Interactivity\Blocks\Report\ReportContext;
use ElioBlocks\Settings\PluginSettings;
use ElioBlocks\WeatherForecast\WeatherForecastAdapterInterface;
use ElioBlocks\Weather\Condition\Icons\ConditionIconCollectionResolver;
use ElioBlocks\Weather\Condition\Icons\ConditionIconsRegistry;

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

/**
 * Registers a provider: an organization the data comes from, and what it serves.
 *
 * Must be called on the 'elio_blocks_init' action. A provider the registry
 * refuses (malformed slug, label or credential name, attribution URL not
 * http(s), duplicate slug, registry already locked) gets a _doing_it_wrong()
 * notice, as register_block_type() does.
 *
 * A provider that needs to identify the site (an API key, an account, a
 * contact address) declares its credentials: the settings page gives it a card
 * with their fields, and its adapters get their values in fetch(). One whose
 * license asks for a credit wherever its data is shown declares its
 * attribution: the provider-attribution block prints it in the reports. What
 * it serves are its adapters, one per domain: a WeatherForecastAdapterInterface
 * for the weather forecast.
 *
 *   use ElioBlocks\Provider\Provider;
 *   use ElioBlocks\Provider\ProviderAttribution;
 *   use ElioBlocks\Provider\ProviderCredential;
 *
 *   elio_blocks_register_provider( new Provider(
 *       'my-provider',
 *       'My Provider',
 *       array( new ProviderCredential( 'api_key', __( 'API Key', 'my-plugin' ), required: true, secret: true ) ),
 *       new ProviderAttribution( 'https://my-provider.example/', 'CC BY 4.0', 'https://creativecommons.org/licenses/by/4.0/' ),
 *       array( new MyWeatherForecastAdapter() ),
 *   ) );
 *
 * or with a class of its own extending Provider, as the built-in OpenMeteo.
 * Each credential can also be set with the constant ELIO_BLOCKS_{SLUG}_{NAME}
 * (uppercased, hyphens as underscores).
 *
 * @param Provider $provider The provider, with its credentials, attribution and adapters.
 * @return bool True if the provider was registered, false otherwise.
 * @since 0.1.0
 * @since 0.4.0 Takes a Provider, which holds its credentials, attribution and
 *              adapters, in place of a slug and an array.
 *              elio_blocks_register_weather_forecast_provider() is gone: an
 *              adapter is one of the adapters of its provider.
 */
function elio_blocks_register_provider( Provider $provider ): bool {
	return Plugin::instance()->container()->get( ProviderRegistry::class )->register( $provider );
}

/**
 * Registers a condition icon collection, a namespace for icons.
 *
 * Must be called on the 'elio_blocks_init' action, before the icons of the collection.
 *
 * @param string               $slug Collection slug: lowercase letters, digits, hyphens, underscores.
 * @param array<string, mixed> $args {
 *     @type string $label        Required. Human-readable label, shown in the editor.
 *     @type string $description  Optional. Human-readable description.
 *     @type float  $stroke_width Optional. Stroke width the stroke icons are drawn with, what the condition icon
 *                                block applies unless set on the block. Default 2.
 * }
 * @return bool True if the collection was registered, false otherwise.
 * @since 0.1.0
 * @since 0.2.0 Takes a stroke_width.
 */
function elio_blocks_register_condition_icon_collection( string $slug, array $args ): bool {
	return Plugin::instance()->container()->get( ConditionIconsRegistry::class )->registerCollection( $slug, $args );
}

/**
 * Unregisters a condition icon collection and its icons.
 *
 * Must be called on the 'elio_blocks_init' action.
 *
 * @param string $slug Collection slug.
 * @return bool True if the collection was unregistered, false otherwise.
 * @since 0.1.0
 */
function elio_blocks_unregister_condition_icon_collection( string $slug ): bool {
	return Plugin::instance()->container()->get( ConditionIconsRegistry::class )->unregisterCollection( $slug );
}

/**
 * Registers a condition icon in a registered collection.
 *
 * Must be called on the 'elio_blocks_init' action.
 *
 * @param string               $name Qualified name, "collection/icon-name".
 * @param array<string, mixed> $args {
 *     @type string $content    SVG markup. Required unless file_path is given.
 *     @type string $file_path  Absolute path of an .svg file, read when the icon is first shown.
 *     @type string $label      Optional. Human-readable label.
 *     @type string $style      Optional. 'fill' (default) or 'stroke': a stroke icon takes the stroke width of the block.
 *     @type array  $conditions Optional. Conditions the icon represents: array( WMO condition slug (WmoConditionCodes),
 *                              'day'|'night'|'all' ) pairs. Each pair is represented by one icon per collection; a block shows no icon
 *                              for a condition its collection does not represent.
 * }
 * @return bool True if the icon was registered, false otherwise.
 * @since 0.1.0
 */
function elio_blocks_register_condition_icon( string $name, array $args ): bool {
	return Plugin::instance()->container()->get( ConditionIconsRegistry::class )->registerIcon( $name, $args );
}

/**
 * Unregisters a condition icon.
 *
 * Must be called on the 'elio_blocks_init' action.
 *
 * @param string $name Qualified icon name.
 * @return bool True if the icon was unregistered, false otherwise.
 * @since 0.1.0
 */
function elio_blocks_unregister_condition_icon( string $name ): bool {
	return Plugin::instance()->container()->get( ConditionIconsRegistry::class )->unregisterIcon( $name );
}

/**
 * Adds an icon to the sprite of the page, the symbols condition icons point at.
 *
 * Condition-icon blocks add the icons they show; the report block around them
 * prints the sprite (elio_blocks_render_icon_sprite()). An icon the page has
 * already is not printed again.
 *
 * @param string $name Qualified icon name.
 * @param string $svg  Sanitized SVG markup, the content of elio_blocks_get_condition_icon().
 * @return void
 * @since 0.1.0
 */
function elio_blocks_add_icon_to_sprite( string $name, string $svg ): void {
	Plugin::instance()->container()->get( IconSprite::class )->add( $name, $svg );
}

/**
 * Returns the sprite of the icons added since the last call and not printed yet.
 *
 * For the report block, after its inner blocks rendered: printed before them,
 * the symbols reach the browser before the icons using them.
 *
 * @return string Hidden <svg> holding one <symbol> per icon, empty when there is none.
 * @since 0.1.0
 */
function elio_blocks_render_icon_sprite(): string {
	return Plugin::instance()->container()->get( IconSprite::class )->render();
}

/**
 * Returns the state of the elio/weather-report store, for wp_interactivity_state().
 *
 * The weather forecast endpoint, how long a weather forecast stays fresh, the
 * refresh interval, and the derived values (state.*) the blocks of a report
 * print.
 *
 * @return array<string, mixed>
 * @since 0.1.0
 */
function elio_blocks_get_weather_report_interactivity_state(): array {
	return Plugin::instance()->container()->get( DirectivesHelper::class )->getState();
}

/**
 * Returns the interactivity context of a weather report block (data-wp-context).
 *
 * Its location, provider and units, the signature of the requests its view
 * script sends, and its weather forecast, fetched now (or read from the cache).
 * Not the block context ($block->context) the report gives its inner blocks.
 *
 * @param WP_Block $block Weather report block being rendered.
 * @return array<string, mixed>
 * @since 0.1.0
 */
function elio_blocks_get_weather_report_interactivity_context( WP_Block $block ): array {
	return Plugin::instance()->container()->get( DirectivesHelper::class )->getContext( $block );
}

/**
 * Returns the current conditions of the weather report being rendered.
 *
 * An item like the rows of elio_blocks_get_forecast_items() (temperature,
 * condition_icons…); null when the report has no weather forecast.
 *
 * @return array<string, mixed>|null
 * @since 0.1.0
 */
function elio_blocks_get_current_conditions(): ?array {
	return Plugin::instance()->container()->get( ReportContext::class )->getCurrentItem();
}

/**
 * Returns the rows of a forecast list of the weather report being rendered.
 *
 * Hourly rows start at the hour in progress. Empty when the report has no
 * weather forecast.
 *
 * @param string $type  'daily' or 'hourly'.
 * @param int    $count Number of rows.
 * @return list<array<string, mixed>>
 * @since 0.1.0
 */
function elio_blocks_get_forecast_items( string $type, int $count ): array {
	return Plugin::instance()->container()->get( ReportContext::class )->getForecastItems( $type, $count );
}

/**
 * Returns an icon of the weather report being rendered.
 *
 * Items point to their icon by qualified name, in condition_icons[ collection ].
 * Null when the weather forecast of the report has no such icon.
 *
 * @param string $name Qualified icon name ("elio/sun").
 * @return array{content: string, style: string}|null Sanitized SVG markup, and 'fill' or 'stroke'.
 * @since 0.1.0
 */
function elio_blocks_get_condition_icon( string $name ): ?array {
	return Plugin::instance()->container()->get( ReportContext::class )->getIcon( $name );
}

/**
 * Returns the icon collection a condition-icon block shows.
 *
 * Its own, else the one of its report, else the one of the site, else the
 * plugin one ("elio"). A collection that is not registered counts as not chosen.
 *
 * @param string|null $block_collection  The iconCollection attribute of the block.
 * @param string|null $report_collection The elio/reportIconCollection block context.
 * @return string Collection slug.
 * @since 0.1.0
 */
function elio_blocks_get_condition_icon_collection( ?string $block_collection, ?string $report_collection ): string {
	return Plugin::instance()->container()->get( ConditionIconCollectionResolver::class )->resolve( $block_collection, $report_collection );
}

/**
 * Returns the stroke width the stroke icons of a collection are drawn with.
 *
 * What a condition-icon block applies to its symbol unless its strokeWidth
 * attribute says otherwise: 2 for a collection that declares none, or that is
 * not registered.
 *
 * @param string $collection Collection slug.
 * @return float Stroke width, in the units of the 24×24 viewBox.
 * @since 0.2.0
 */
function elio_blocks_get_condition_icon_stroke_width( string $collection ): float {
	$registered = Plugin::instance()->container()->get( ConditionIconsRegistry::class )->getRegisteredCollection( $collection );

	return $registered['stroke_width'] ?? ConditionIconsRegistry::DEFAULT_STROKE_WIDTH;
}

/**
 * Returns the credit the weather forecast of a provider is shown with, as the
 * license of the provider asks.
 *
 * Null when the provider asks for none, or serves no weather forecast.
 *
 * @param string $provider Provider slug (the elio/reportProvider block context), empty for the site default.
 * @return array{name: string, url: string, license: string, license_url: string}|null Label of the provider, its site,
 *                                                                                  the license of its data and its page; to escape.
 * @since 0.2.0
 */
function elio_blocks_get_weather_forecast_attribution( string $provider ): ?array {
	$container = Plugin::instance()->container();
	if ( '' === $provider ) {
		$provider = $container->get( PluginSettings::class )->getDefaultWeatherForecastProvider();
	}

	$provider    = $container->get( ProviderRegistry::class )->getBySlug( $provider );
	$attribution = $provider?->attribution;
	if ( null === $attribution || null === $provider->getAdapter( WeatherForecastAdapterInterface::class ) ) {
		return null;
	}

	return array(
		'name'        => $provider->label,
		'url'         => $attribution->url,
		'license'     => $attribution->license,
		'license_url' => $attribution->licenseUrl,
	);
}