1<?php
  2/**
  3 * Interactivity API: Functions and hooks
  4 *
  5 * @package WordPress
  6 * @subpackage Interactivity API
  7 * @since 6.5.0
  8 */
  9
 10/**
 11 * Retrieves the main WP_Interactivity_API instance.
 12 *
 13 * It provides access to the WP_Interactivity_API instance, creating one if it
 14 * doesn't exist yet.
 15 *
 16 * @since 6.5.0
 17 *
 18 * @global WP_Interactivity_API $wp_interactivity
 19 *
 20 * @return WP_Interactivity_API The main WP_Interactivity_API instance.
 21 */
 22function wp_interactivity(): WP_Interactivity_API {
 23	global $wp_interactivity;
 24	if ( ! ( $wp_interactivity instanceof WP_Interactivity_API ) ) {
 25		$wp_interactivity = new WP_Interactivity_API();
 26	}
 27	return $wp_interactivity;
 28}
 29
 30/**
 31 * Processes the interactivity directives contained within the HTML content
 32 * and updates the markup accordingly.
 33 *
 34 * @since 6.5.0
 35 *
 36 * @param string $html The HTML content to process.
 37 * @return string The processed HTML content. It returns the original content when the HTML contains unbalanced tags.
 38 */
 39function wp_interactivity_process_directives( string $html ): string {
 40	return wp_interactivity()->process_directives( $html );
 41}
 42
 43/**
 44 * Gets and/or sets the initial state of an Interactivity API store for a
 45 * given namespace.
 46 *
 47 * If state for that store namespace already exists, it merges the new
 48 * provided state with the existing one.
 49 *
 50 * The namespace can be omitted inside derived state getters, using the
 51 * namespace where the getter is defined.
 52 *
 53 * @since 6.5.0
 54 * @since 6.6.0 The namespace can be omitted when called inside derived state getters.
 55 *
 56 * @param string $store_namespace The unique store namespace identifier.
 57 * @param array  $state           Optional. The array that will be merged with the existing state for the specified
 58 *                                store namespace.
 59 * @return array The state for the specified store namespace. This will be the updated state if a $state argument was
 60 *               provided.
 61 */
 62function wp_interactivity_state( ?string $store_namespace = null, array $state = array() ): array {
 63	return wp_interactivity()->state( $store_namespace, $state );
 64}
 65
 66/**
 67 * Gets and/or sets the configuration of the Interactivity API for a given
 68 * store namespace.
 69 *
 70 * If configuration for that store namespace exists, it merges the new
 71 * provided configuration with the existing one.
 72 *
 73 * @since 6.5.0
 74 *
 75 * @param string $store_namespace The unique store namespace identifier.
 76 * @param array  $config          Optional. The array that will be merged with the existing configuration for the
 77 *                                specified store namespace.
 78 * @return array The configuration for the specified store namespace. This will be the updated configuration if a
 79 *               $config argument was provided.
 80 */
 81function wp_interactivity_config( string $store_namespace, array $config = array() ): array {
 82	return wp_interactivity()->config( $store_namespace, $config );
 83}
 84
 85/**
 86 * Generates a `data-wp-context` directive attribute by encoding a context
 87 * array.
 88 *
 89 * This helper function simplifies the creation of `data-wp-context` directives
 90 * by providing a way to pass an array of data, which encodes into a JSON string
 91 * safe for direct use as a HTML attribute value.
 92 *
 93 * Example:
 94 *
 95 *     <div <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => true, 'count' => 0 ) ); ?>>
 96 *
 97 * @since 6.5.0
 98 *
 99 * @param array  $context         The array of context data to encode.
100 * @param string $store_namespace Optional. The unique store namespace identifier.
101 * @return string A complete `data-wp-context` directive with a JSON encoded value representing the context array and
102 *                the store namespace if specified.
103 */
104function wp_interactivity_data_wp_context( array $context, string $store_namespace = '' ): string {
105	return 'data-wp-context=\'' .
106		( $store_namespace ? $store_namespace . '::' : '' ) .
107		( empty( $context ) ? '{}' : wp_json_encode( $context, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP ) ) .
108		'\'';
109}
110
111/**
112 * Gets the current Interactivity API context for a given namespace.
113 *
114 * The function should be used only during directive processing. If the
115 * `$store_namespace` parameter is omitted, it uses the current namespace value
116 * on the internal namespace stack.
117 *
118 * It returns an empty array when the specified namespace is not defined.
119 *
120 * @since 6.6.0
121 *
122 * @param string $store_namespace Optional. The unique store namespace identifier.
123 * @return array The context for the specified store namespace.
124 */
125function wp_interactivity_get_context( ?string $store_namespace = null ): array {
126	return wp_interactivity()->get_context( $store_namespace );
127}
128
129/**
130 * Returns an array representation of the current element being processed.
131 *
132 * The function should be used only during directive processing.
133 *
134 * @since 6.7.0
135 *
136 * @return array{attributes: array<string, string|bool>}|null Current element.
137 */
138function wp_interactivity_get_element(): ?array {
139	return wp_interactivity()->get_element();
140}
141