Allow more control over which forms trigger Instant Results

[JakePT]

Is your enhancement related to a problem? Please describe.
Currently, Instant Results is attached to any input[name="s"] elements on the page, and triggered whenever the form that contains this input is submitted. This targets the Search widget, block, the output of get_search_form() in most themes, and any form that submits a query that includes the standard WordPress search parameter (s).

Therefore it's not currently possible to remove Instant Results from specific search form instances, or to bind it to other forms or even buttons.

A potential use case for this is that because Instant Results only has a single configuration for facets, the user may want to only enable it for Products search.

Describe the solution you'd like
There are several options for addressing this:

• Implement a filter to allow developers control over the selector used to target forms and inputs.
• Implement a setting to allow any user to change the selector used, a la Autosuggest.
• Expose an API to allow developers to bind Instant Results to any element or event they wish.

Implementation of any solution is slightly more complicated compare to Autosuggest, as the current behaviour requires a form and an input, as Instant Results is displayed based on the submit event on the form, but the search term is pulled from the instance of the input in that form.

If an API were exposed it would need the capability to not only open the Instant Results modal, but also to potentially populate the search term and other parameters.

[JakePT]

Instant Results is currently launched by submitting any form that contains an input[name="s"] and on submission of that form it takes the value of that input and triggers a search with that search term. Since we're interacting with two elements here it makes a setting like Autosuggest more difficult because there isn't necessarily a single selector that a user could enter.

We could allow a user to enter a selector like .search-field into a setting, but if that field isn't properly inside a <form> then we couldn't trigger Instant Results on submission. Also, just adding a field for a selector doesn't allow much more control over how Instant Results is launched. For example, if the user adds a search form with a dropdown for orderby we don't currently have a way to apply that to the search (we only support post_type). This will be more common now that WordPress/gutenberg#40585 is apparently implemented, and more so if a UI is ever implemented. Instant Results also can't be launched by just clicking a button.

Instead of/in addition to a selector field I think we should expose a JavaScript function that can be used to open the Instant Results modal and populate query args. Developers could then set default arguments of the query with their own values or by populating the arguments with values from their form.

So something like this would be possible:

button.addEventListener('click', () => {
	window.epInstantResults.open({
		post_type: 'product',
	});
});

We would then update Instant Results to use this function ourselves for the default behaviour and add support for automatically setting arguments based on any inputs for post_type, order, orderby, per_page etc.

I think this would also be an opportunity to try and decouple Instant Results from the modal, so that we can theoretically support embedding Instant Results as a block or similar without the modal.

[JakePT]

On discovery I think we can break this down and handle this task in two parts, and move decoupling Instant Results from the modal into a separate issue.

The two things that need to be done here:

1. Support a public method for triggering Instant Results to open. I think a good way to do this would be a custom action that could be called with doAction() which Instant Results would listen to instead of the form submission event.
   1. Then we can pull out the event listener into a function outside of the React app and call the action with doAction() from there. 3rd-party developers could open instant results themselves with a call to doAction(). This action would accept arguments so that things like the search term, post type, or ordering could be sent with the action. Developers could also remove the default action with removeAction() so that only their custom trigger works.
   2. Our event listener would continue to pass the arguments we already support from from the form, namely the search term and the post type.
2. The next step would be to update the default event listener to support more fields in the search form, so that fields for things like order or orderby could also be set based on form values when opening Instant Results. This should be achievable by converting the form data to URL parameters and passing those through getArgsFromUrlParams().
   1. This would enable support for setting more search parameters from a search form, but Instant Results doesn't always use the same parameters that pre-existing search forms might. For example, a default wp_dropdown_categories() will use cat but Instant Results will only filter by category when using tax-category. So if we want to support Instant Results for existing search forms not built with Instant Results in mind, or even future changes to the search block as outlined on Search Block - ability to specify additional search query vars WordPress/gutenberg#40585, we may need to map some parameters to our parameter names.

I will file a new issue for #2, and another issue for decoupling Instant Results from the modal, and we can proceed with #1 to progress this issue.

[JakePT]

Created #2978 for #2 above.

[JakePT]

Created #2979 for decoupling Instant Results from the modal.