<?php
/**
 * Template functions for theme and plugin authors.
 *
 * The fourth way to put a map on a page, after the block, the shortcode and
 * the widget area. It exists because a theme's only other route into the
 * renderer is `do_shortcode( '[mapsemble id="13"]' )`, which gives no argument
 * checking and reads like a workaround — which it is.
 *
 * These are global functions on purpose: a template is not a place to be
 * reaching into a namespaced singleton.
 *
 * @package Mapsemble
 */

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

if ( ! function_exists( 'mapsemble_map' ) ) {
	/**
	 * Returns the markup for one map.
	 *
	 * ```php
	 * echo mapsemble_map( 13, [ 'height' => '70vh' ] );
	 * ```
	 *
	 * @param int   $map_id Post id of the map, as shown in the shortcode on
	 *                      Mapsemble → Maps.
	 * @param array $args   Optional. `height`, `scroll_capture`,
	 *                      `scroll_offset_top`, `scroll_offset_bottom`,
	 *                      `fill_viewport` (only 'false' does anything), and
	 *                      `filters` — a native array of filter slug => value
	 *                      (or list of values) applied when the map loads.
	 *                      Lengths are CSS lengths (`50vh`, `480px`); an
	 *                      unrecognised value is ignored rather than emitted,
	 *                      so the map keeps its own default.
	 * @return string The markup, or '' when the plugin has not booted yet.
	 */
	function mapsemble_map( int $map_id, array $args = array() ): string {
		// Themes load long after `plugins_loaded`, so this only trips for code
		// running unusually early — where the honest answer is to say so
		// rather than to fatal on an uninitialised renderer.
		if ( ! did_action( 'plugins_loaded' ) ) {
			_doing_it_wrong(
				__FUNCTION__,
				esc_html__( 'Mapsemble maps cannot be rendered before the plugins_loaded hook.', 'mapsemble' ),
				'0.1.0'
			);
			return '';
		}

		return \Mapsemble\Plugin::instance()->embed()->render( $map_id, $args );
	}
}

if ( ! function_exists( 'the_mapsemble_map' ) ) {
	/**
	 * Echoes the markup for one map.
	 *
	 * @param int   $map_id Post id of the map.
	 * @param array $args   See mapsemble_map().
	 */
	function the_mapsemble_map( int $map_id, array $args = array() ): void { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- the WP template-tag idiom (the_title, the_content) wrapping the prefixed function; public API since 0.1.
		// The renderer's own output: a container div plus a loading message,
		// every dynamic part of it already escaped where it was built.
		echo mapsemble_map( $map_id, $args ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
	}
}

if ( ! function_exists( 'mapsemble_embed' ) ) {
	/**
	 * Returns the markup for a map embedded by its Mapsemble map id.
	 *
	 * No configuration post is needed: any map on the connected account —
	 * or any public Mapsemble map whose id you have — embeds directly, and
	 * `'sample'` renders the published sample map, which needs no account
	 * at all. A map id bound to a site-fed configuration automatically
	 * serves from this site.
	 *
	 * @param string $map_id A Mapsemble map id, or 'sample'.
	 * @param array  $args   See mapsemble_map().
	 * @return string The markup, or '' when the plugin has not booted yet.
	 */
	function mapsemble_embed( string $map_id, array $args = array() ): string {
		if ( ! did_action( 'plugins_loaded' ) ) {
			_doing_it_wrong(
				__FUNCTION__,
				esc_html__( 'Mapsemble maps cannot be rendered before the plugins_loaded hook.', 'mapsemble' ),
				'0.3.0'
			);
			return '';
		}

		return \Mapsemble\Plugin::instance()->embed()->render_by_map_id( $map_id, $args );
	}
}

if ( ! function_exists( 'the_mapsemble_embed' ) ) {
	/**
	 * Echoes the markup for a map embedded by its Mapsemble map id.
	 *
	 * @param string $map_id A Mapsemble map id, or 'sample'.
	 * @param array  $args   See mapsemble_map().
	 */
	function the_mapsemble_embed( string $map_id, array $args = array() ): void { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound -- the WP template-tag idiom wrapping the prefixed function; see the_mapsemble_map().
		// The renderer's own output: a container div plus a loading message,
		// every dynamic part of it already escaped where it was built.
		echo mapsemble_embed( $map_id, $args ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
	}
}