Added find-in-page definitions - #5770

I'm probably a bit out of my depth here, so any and all feedback is appreciated :)

@domenic @annevk

Thanks! I'm happy to give some editorial feedback, but I think first we should change up the structure a bit.

In general, defining something that isn't referenced is bad. So we want to weave these into a handwavey narrative description of the feature, instead of having them be standalone definitions.

I think this can be accomplished with a minimal modification of what you have here. Basically, instead of bullet points, use paragraphs. And add lots of cross-references, so that it's clear how they relate. For example:

Access to the find-in-page feature is provided via a find-in-page dialog, which is a part of the user interface which allows the user to specify....

Each invocation of the find-in-page feature is scoped to a given query, which is a string that the user wants to find in the page. This is typically entered via the [find-in-page dialog].

Each invocation of the find-in-page feature can produce zero or more matches. These are pieces of content on the page that satisfy the current [query]. Matches may be highlighted by the user agent, to indicate that they satisfy the [query].

...

Questions:

• Probably the query should not just be a string, but also allow for other options, like case-sensitivity, whole-word, etc.?

• Should the matches be defined in terms of actual DOM primitives, e.g. ranges?

• Must every find-in-page invocation have an active match concept?

Thanks for the suggestions! It makes a lot of sense to change it. I'll update it.

• Probably the query should not just be a string, but also allow for other options, like case-sensitivity, whole-word, etc.?

Yeah that makes sense. I think I can just describe this in abstract terms and say as an example, it can be as simple as a string?

• Should the matches be defined in terms of actual DOM primitives, e.g. ranges?

I'm not sure. It makes sense to me, but I'm also weary of writing something down that makes existing implementations not quite spec compliant. I do think it's OK to do as ranges.

• Must every find-in-page invocation have an active match concept?

If there is a match, then there's always an active match (at least in my tests). I think it makes sense to spec that. Of course, if there is no match at all then there is no active match, so (pedantically speaking) not every find-in-page results in an active match.

PTAL, let me know if this is what you meant by structure changes.

This looks great! Some minor points:

• I think the section should probably be normative. Although it doesn't mandate a lot, it's a good number of "statements of fact", and so I think falls on the normative side of the line. Or at least, it doesn't seem good to me to explicitly call it out as non-normative.

• The word "dialog" seems a bit over-prescriptive. Although the spec doesn't mandate that it's a dialog in any way that would cause problems, I think we should probably switch it to something more neutral like "interface". E.g. I think it would be hard to call Firefox's find-in-page UI a dialog.

And one more substantial point:

• Should the active match affect window.getSelection()? If so we'll want to state that normatively somewhere... If not, stating the opposite normatively might also be good. I guess https://w3c.github.io/selection-api/#dfn-selection is the relevant underlying concept here.

• Should the active match affect window.getSelection()? If so we'll want to state that normatively somewhere... If not, stating the opposite normatively might also be good. I guess https://w3c.github.io/selection-api/#dfn-selection is the relevant underlying concept here.

I think this one specifically is a bit tricky, since the browsers currently disagree.

I know that Firefox does affect selection as you type a query. In Chrome, however, the selection only changes if you dismiss a find-in-page interface, in which case the last active match becomes selected.

Would stating this using "may" language normatively be sufficient? Ie something along the lines of "Active match may also cause window.getSelection() to be changed"..

I do think calling out the interplay between find-in-page and selection is important, and I will do that, I just think it's hard to mandate specific behavior since the existing behavior is not the same across browsers.

PTAL

This is looking good. I pushed some editorial changes (e.g. casing, wrapping, updating the link IDs generated by data-x, adding an XXX box referencing #4500).

I think we should be more lenient about the interaction with selection, if things are currently not interoperable. In particular, I don't think we have a goal of converging everyone's behavior here, since it is untestable and cannot cause interop problems (right?). That is, I don't think it's possible to distinguish between update-on-dismissal and update-while-you-type; people could just type a character, dismiss the UI, reopen the UI, type a second character, etc. to get the same behavior as update-while-you-type.

So in particular the current phrasing seems contradictory:

Specifically, when the find-in-page interface is dismissed, the last active match is selected. The selection may either be updated as the active match changes or only when the find-in-page interface is dismissed.

The first sentence seems to mandate on-dismissal, whereas the second seems to allow as-you-type.

I think we should instead make a more vague, saying something like how the active match will be tied to the current selection, but selection may update at a different time than the active match updates, e.g. only upon dismissal. Or something. You've been coming up with great phrasing so far, so I'll leave that to you :).

I pushed some editorial changes (e.g. casing, wrapping, updating the link IDs generated by data-x, adding an XXX box referencing #4500).

Awesome thanks! But did you mean #3539 ?

I'll update the phrasing, I can see how it reads as contradictory

I did, sorry, I was confusing different issues I was recently looking at! If you could update that box while you're there that'd be great.

PTAL, I think it reads a bit better albeit a bit vaguer :P which was the intent.