HTML API: Add set/get inner/outer functions

src/wp-admin/includes/template.php

@@ -2540,20 +2540,20 @@ function compression_test() {
  *
  * @see get_submit_button()
  *
- * @param string       $text             Optional. The text of the button. Defaults to 'Save Changes'.
+ * @param string       $text             The text of the button (defaults to 'Save Changes')
  * @param string       $type             Optional. The type and CSS class(es) of the button. Core values
  *                                       include 'primary', 'small', and 'large'. Default 'primary'.
- * @param string       $name             Optional. The HTML name of the submit button. If no `id` attribute
- *                                       is given in the `$other_attributes` parameter, `$name` will be used
- *                                       as the button's `id`. Default 'submit'.
- * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph tag,
- *                                       false otherwise. Default true.
- * @param array|string $other_attributes Optional. Other attributes that should be output with the button,
- *                                       mapping attributes to their values, e.g. `array( 'id' => 'search-submit' )`.
- *                                       These key/value attribute pairs will be output as `attribute="value"`,
- *                                       where attribute is the key. Attributes can also be provided as a string,
- *                                       e.g. `id="search-submit"`, though the array format is generally preferred.
- *                                       Default null.
+ * @param string       $name             The HTML name of the submit button. Defaults to "submit". If no
+ *                                       id attribute is given in $other_attributes below, $name will be
+ *                                       used as the button's id.
+ * @param bool         $wrap             True if the output button should be wrapped in a paragraph tag,
+ *                                       false otherwise. Defaults to true.
+ * @param array|string $other_attributes Other attributes that should be output with the button, mapping
+ *                                       attributes to their values, such as setting tabindex to 1, etc.
+ *                                       These key/value attribute pairs will be output as attribute="value",
+ *                                       where attribute is the key. Other attributes can also be provided
+ *                                       as a string such as 'tabindex="1"', though the array format is
+ *                                       preferred. Default null.
  */
 function submit_button( $text = null, $type = 'primary', $name = 'submit', $wrap = true, $other_attributes = null ) {
 	echo get_submit_button( $text, $type, $name, $wrap, $other_attributes );
@@ -2564,20 +2564,20 @@ function submit_button( $text = null, $type = 'primary', $name = 'submit', $wrap
  *
  * @since 3.1.0
  *
- * @param string       $text             Optional. The text of the button. Defaults to 'Save Changes'.
+ * @param string       $text             Optional. The text of the button. Default 'Save Changes'.
  * @param string       $type             Optional. The type and CSS class(es) of the button. Core values
  *                                       include 'primary', 'small', and 'large'. Default 'primary large'.
- * @param string       $name             Optional. The HTML name of the submit button. If no `id` attribute
- *                                       is given in the `$other_attributes` parameter, `$name` will be used
- *                                       as the button's `id`. Default 'submit'.
- * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph tag,
- *                                       false otherwise. Default true.
+ * @param string       $name             Optional. The HTML name of the submit button. Defaults to "submit".
+ *                                       If no id attribute is given in $other_attributes below, `$name` will
+ *                                       be used as the button's id. Default 'submit'.
+ * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph
+ *                                       tag, false otherwise. Default true.
  * @param array|string $other_attributes Optional. Other attributes that should be output with the button,
- *                                       mapping attributes to their values, e.g. `array( 'id' => 'search-submit' )`.
- *                                       These key/value attribute pairs will be output as `attribute="value"`,
- *                                       where attribute is the key. Attributes can also be provided as a string,
- *                                       e.g. `id="search-submit"`, though the array format is generally preferred.
- *                                       Default empty string.
+ *                                       mapping attributes to their values, such as `array( 'tabindex' => '1' )`.
+ *                                       These attributes will be output as `attribute="value"`, such as
+ *                                       `tabindex="1"`. Other attributes can also be provided as a string such
+ *                                       as `tabindex="1"`, though the array format is typically cleaner.
+ *                                       Default empty.
  * @return string Submit button HTML.
  */
 function get_submit_button( $text = '', $type = 'primary large', $name = 'submit', $wrap = true, $other_attributes = '' ) {

src/wp-includes/html-api/class-wp-html-open-elements.php

@@ -37,6 +37,17 @@ class WP_HTML_Open_Elements {
 	 */
 	public $stack = array();
 
+	/**
+	 * Holds functions added to be called after popping an element off the stack.
+	 *
+	 * Listeners are passed the WP_HTML_Token for the item that was removed.
+	 *
+	 * @since 6.4.0
+	 *
+	 * @var array
+	 */
+	private $after_pop_listeners = array();
+
 	/**
 	 * Whether a P element is in button scope currently.
 	 *
@@ -428,5 +439,39 @@ public function after_element_pop( $item ) {
 				$this->has_p_in_button_scope = $this->has_element_in_button_scope( 'P' );
 				break;
 		}
+
+		// Call any listeners that are registered.
+		foreach ( $this->after_pop_listeners as $listener ) {
+			call_user_func( $listener, $item );
+		}
+	}
+
+	/**
+	 * Creates a context in which a given listener is called after
+	 * popping an element off of the stack of open elements.
+	 *
+	 * It's unlikely that you will need this function. It exists
+	 * to aid an optimization in the `WP_HTML_Processor` and the
+	 * strange form of calling a generator inside a `foreach`
+	 * loop ensures that proper cleanup of the listener occurs.
+	 *
+	 * Example:
+	 *
+	 *     $did_close  = false;
+	 *     $closed_a_p = function ( $item ) use ( &$did_close ) { $did_close = 'P' === $item->node_name; };
+	 *     foreach ( $stack_of_open_elements->with_pop_listener( $closed_a_p ) ) {
+	 *         while ( ! $did_close && $processor->next_tag() ) {
+	 *             // This loop executes until _any_ P element is closed.
+	 *         }
+	 *     }
+	 *
+	 * @since 6.4.0
+	 *
+	 * @param callable $listener Called with the WP_HTML_Token for the item that was popped off of the stack.
+	 */
+	public function with_pop_listener( $listener ) {
+		$this->after_pop_listeners[] = $listener;
+		yield;
+		array_pop( $this->after_pop_listeners );
 	}
 }