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  */

    22 function 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  */

    39 function 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  */

    62 function 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  */

    81 function 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  */

   104 function 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  */

   125 function wp_interactivity_get_context( ?string $store_namespace = null ): array {

   126 	return wp_interactivity()->get_context( $store_namespace );

   127 }