List extended selectors + caveats in hx-include doc

[Telroshan]

This addresses issue #1509

• hx-include supports the extended selectors, which were not mentioned in its documentation
• The behaviour of find for example, can be confusing when using an inherited hx-include attribute: added a note to explain that
• Extended selectors only return a single element, which could be confusing compared to a standard CSS selector that returns all elements matching that selector: added a note to explain that

[checketts]

Good clarifications!

[alexpetros]

I wonder if copy-pasting that bit about the find, closest, etc. mini-language everywhere is the way to go, or if we shouldn't standardize it somehow.

[Telroshan]

That's the next thing I was going to suggest! 😄
Since they are used for hx-include, hx-indicator, hx-target, hx-trigger's from modifier, and probably others that I'm forgetting, I think we should give the htmx's extended selectors syntax its own page and link to that page in every attribute doc supporting the syntax.
I'm afraid we would inevitably have differences and outdated descriptions in each attribute's doc otherwise

[alexpetros]

My only concern is that I think the trigger syntax and the other ones are parsed separately, which doesn't necessarily mean they should be separate in the documentation, but it's possible they could diverge

[Telroshan]

I hadn't noticed this, indeed others use querySelectorAllExt while getTriggerSpecs does its own parsing.
Though, looking at the code, getTriggerSpecs's logic is just "is the keyword one of the following predefined extended selectors ? If so, parse one more token", but then this parsed selector is also resolved through querySelectorAllExt

• I can't think of any reason hx-trigger's from would need to use a different selectors set than, say, hx-include
• if you're concerned about the duplication here @alexpetros (technically, the extended selectors are hardcoded at 2 places in the code), maybe we could do an array, a map or something else there, to factor the logic and define the selectors only once?
  Probably a dumb idea but what comes to the top of my head is an { "selectorName": function }, such as

var extendedSelectors = {
    "closest": (elt, selector) => [closest(elt, normalizeSelector(selector.substr(8)))],
    "find": (elt, selector) => [find(elt, normalizeSelector(selector.substr(5)))],
    ...
}

(Using the short syntax on purpose here but ofc this isn't IE11 compatible)
Basically querySelectorAllExt's code, but as a map instead of a if-else series, thus something that can be iterated from another place in the code, to loop through all defined extended selectors without hardcoding them once again

[alexpetros]

I wonder if copy-pasting that bit about the find, closest, etc. mini-language everywhere is the way to go, or if we shouldn't standardize it somehow.

After letting this sit for too long, I've decided that just because we should do this eventually isn't a reason to hold up this PR. This is at least a step in the right direction.