Highlight the anchor target

[gibson042]

I think highlighting the anchor target would help readability, especially for refs. Specific colors and styles could obviously be tweaked, though.

Preview (ref)

Preview (section)

[bakkot]

I am fine with the general concept, but I find this styling unpleasant, especially without a way to clear it. Maybe just the background color, and fading out over a couple seconds?

(I don't have much design background, alas.)

[gibson042]

@bakkot I don't have design credentials either, so this seems to be a matter of taste. Would you settle for just the background highlight without the fade out, and/or different styling for emu-xref vs. emu-clause (allowing reference highlighting to be cleared by navigating to its containing clause)?

Either way, I'm happy to make style tweaks myself or to leave them to you.

[michaelficarra]

This will just show a highlighted background briefly:

@keyframes highlight-target-bg {
  0% {
    background-color: rgba(249, 241, 172, 0)
  }
  20% {
    background-color: rgba(249, 241, 172, 1);
  }
  100%{
    background-color: rgba(249, 241, 172, 0)
  }
}

:target {
  animation: highlight-target-bg 1.5s cubic-bezier(0.22, 0.61, 0.36, 1);
}

You can try it out by copy-pasting it into the ecmarkup.css file in devtools and then clicking some spec-internal links.

We could also consider just doing dfn:target or maybe emu-clause emu-clause emu-clause:target, dfn:target to avoid highlighting big upper-level sections.

[bakkot]

Editors briefly chatted and all prefer the fade-out; Michael's snippet WFM.

[gibson042]

The workflow for which I care about this most is visiting references to an operation or definition, where the :target is therefore an <emu-xref> and I will frequently open many references in background tabs to visit in succession. Fading back to normal destroys that case because it will be done by the time I get there. What would you think about fading it for sectioning elements but leaving it on for <emu-xref>?

[bakkot]

I really don't like any option where the highlight persists, for any element. My usual working mode is clicking a reference and then scrolling around; having the highlight stay on page is quite distracting.

For your workflow, would you be satisfied by some logic such that for pages which are not currently visible the highlight is persisted until 2 seconds after the page becomes visible?

[bakkot]

Unrelated to the above, I don't like that this highlights sections when clicking on links in the table of contents. Maybe exclude emu-clause and emu-annex?

[gibson042]

I really don't like any option where the highlight persists, for any element. My usual working mode is clicking a reference and then scrolling around; having the highlight stay on page is quite distracting.

If the styling persists only on <emu-xref>, then a straightforward way to clear it would be navigating to the containing section already visible and distinguished in the menu pane. I already have local shortcuts for effectively this.

For your workflow, would you be satisfied by some logic such that for pages which are not currently visible the highlight is persisted until 2 seconds after the page becomes visible?

"satisfied" is a bit strong, but yeah, I can live with that.

Unrelated to the above, I don't like that this highlights sections when clicking on links in the table of contents. Maybe exclude emu-clause and emu-annex?

I actually thought that was a bit of a feature for visually showing when a section with a short introduction has subsections, especially deep in the hierarchy where the font size of headings is similar (e.g., 10.1.5 [[GetOwnProperty]] or 20.1.2.3 Object.defineProperties). Is it the highlighting that you don't like, or how striking the background fade is? We could also use entirely different styling, e.g. a colored vertical bar on the side:

[michaelficarra]

Unrelated to the above, I don't like that this highlights sections when clicking on links in the table of contents. Maybe exclude emu-clause and emu-annex?

I've updated the selector to exclude non-leaf clauses and annexes. Should just apply to <dfn>, <emu-xref>, and leaf <emu-clause> nodes now.

[michaelficarra]

@gibson042 I've added a subtle persistent highlight like you've suggested. Can you try it out and let me know what you think?

[michaelficarra]

@gibson042 I've split the persistent indicator into #552 as to not hold up the temporary highlight that seems generally acceptable.

[bakkot]

Is it the highlighting that you don't like, or how striking the background fade is?

It's having any visual change at all. To me the table of contents is a normal way of navigating within the document, and I don't expect things to visually change based on how I'm navigating within a document. That is, I expect the table of contents to work like it does on Wikipedia, MDN, or pretty much any other page; I don't want it to have any special effect on the document itself.

[gibson042]

To me the table of contents is a normal way of navigating within the document, and I don't expect things to visually change based on how I'm navigating within a document. That is, I expect the table of contents to work like it does on Wikipedia, MDN, or pretty much any other page; I don't want it to have any special effect on the document itself.

Wouldn't it be more strange for the visual effects to vary based on how you got to an anchor, acting one way from the TOC but a different way based on links internal to the content? Also, although :target styling isn't (yet?) common, there are examples at e.g. https://wordpress.org/documentation/article/wordpress-glossary/#gravatar and https://fetch.spec.whatwg.org/#concept-request-url .

This really is the complement to highlighting the active section in the menu pane, which we've been doing for a long time.

[bakkot]

Wouldn't it be more strange for the visual effects to vary based on how you got to an anchor, acting one way from the TOC but a different way based on links internal to the content?

I agree it's a little strange, but certainly not more strange.

Anyway, the thing I've actually proposed here is to not apply any styling to emu-clause or emu-annex, which are the only things in the table of contents, and that would mean that you get the same styling no matter how you navigate to an anchor. So no additional strangeness at all.

and https://fetch.spec.whatwg.org/#concept-request-url .

So, the styling there is exactly what I want: a subtle highlight, applied only words or phrases rather than to clauses or headers (and, therefore, never when navigating from the ToC, since those things are not in the ToC), and fading out entirely after a couple seconds.

Let's just do that (possibly with the addition of some logic to ensure the fade doesn't actually begin until the page is visible) instead of inventing something new.

[gibson042]

Anyway, the thing I've actually proposed here is to not apply any styling to emu-clause or emu-annex, which are the only things in the table of contents, and that would mean that you get the same styling no matter how you navigate to an anchor. So no additional strangeness at all.

What about the new side indicator from #552? I can see shifting target section styling to only that, but without it we lose too much IMO.

and https://fetch.spec.whatwg.org/#concept-request-url .

So, the styling there is exactly what I want: a subtle highlight, applied only words or phrases rather than to clauses or headers (and, therefore, never when navigating from the ToC, since those things are not in the ToC), and fading out entirely after a couple seconds.

The color fades out entirely, but the indication does not (at least on my machine) because the inline target is focused. So it actually has the persistence that I consider important in the form of a focus ring (but is trivially dismissable).

[bakkot]

What about the new side indicator from https://github.com/tc39/ecmarkup/pull/552?

That is the specific thing I most object to. I very specifically do not want any additional styling applied when navigating from the ToC, and I would prefer to not apply additional styling to targeted emu-clause or emu-annex elements regardless of how they are navigated to. No sidebar, no highlighting, nothing. We should behave like ~every other document instead of inventing something new.

The color fades out entirely, but the indication does not (at least on my machine) because the inline target is focused.

Huh, I see that border on Chrome but not Firefox, and only when opening in a new tab rather than navigating within the same page (including refreshing). I'm not entirely sure how that works, but I would be fine with replicating that behavior as well.

[gibson042]

That is the specific thing I most object to. I very specifically do not want any additional styling applied when navigating from the ToC, and I would prefer to not apply additional styling to targeted emu-clause or emu-annex elements regardless of how they are navigated to. No sidebar, no highlighting, nothing. We should behave like ~every other document instead of inventing something new.

Hrm, I very specifically do want that styling, for visually indicating the scope of a target section and the location of its boundaries with neighboring sections (which are otherwise non-obvious in many places). Can you explain your objection beyond "most other pages don't have something similar"?

Perhaps it's also worth us talking about synchronously in the next editor call.

[bakkot]

Can you explain your objection beyond "most other pages don't have something similar"?

It's visually distracting; I don't like the content of the document to change out from under me when I'm navigating. (Imagine flipping through a book and colored ink appears and disappear on the pages - that would render the book unreadable.)

Though also, "most other pages don't have something similar" seems like it ought to be sufficient on its own? Ubiquitous UI elements should work consistently across documents.

Happy to chat synchronously though, fair warning, this opinion is very strongly held. We might be able to find something which satisfies us both but it's not going to look anything like the borders in that PR.

[gibson042]

Can you explain your objection beyond "most other pages don't have something similar"?

It's visually distracting; I don't like the content of the document to change out from under me when I'm navigating. (Imagine flipping through a book and colored ink appears and disappear on the pages - that would render the book unreadable.)

I don't think that analogy holds up; this styling applies only when directly visiting a particular section rather than just wandering around... but to address it anyway, I would love for a book to highlight the specific relevant part of a page when I navigate from a TOC or glossary or just follow someone's reference to "page X, paragraph Y" or "§1.2.3" (just like a webpage or ebook does when searching).

Though also, "most other pages don't have something similar" seems like it ought to be sufficient on its own? Ubiquitous UI elements should work consistently across documents.

ecmarkup has many novel affordances for common elements, such as (limiting to those that apply in main content rather than menu or references panes):

• dynamic "can call user code" annotations toggled on pressing "u"
• spec aliases that highlight/unhighlight on click
• a reveal-on-hover section title toolbox for linking/pinning/reference traversal
• copyable hidden text duplicating list item counters

These are good things! And some of them are currently propagating throughout the ecosystem (the WHATWG specs in particular have basically the same alias highlighting and a similar contextual toolbox), just like dynamic TOC active-section highlighting already has. Our goal should not be "do what other pages do", but rather "do what is useful for readers [aligning with other pages where practical and avoiding gratuitous divergence]".

Happy to chat synchronously though, fair warning, this opinion is very strongly held. We might be able to find something which satisfies us both but it's not going to look anything like the borders in that PR.

Acknowledged.

[bakkot]

ecmarkup has many novel affordances for common elements

Those are affordances for things particular to our document - very few webpages have anything like "spec aliases" or "algorithm steps", for example.

do what is useful for readers [aligning with other pages where practical and avoiding gratuitous divergence]

I regard "common UI elements behave the way they commonly do" as being useful for readers.

When there's something which applies uniquely to our document, like spec aliases, that's a reasonable place to try to innovate. When it's something ubiquitous like a table of contents, that's a place to do what everyone else does.

[gibson042]

Very few documents are large like ours, or intended to support entry at arbitrary hyperlinked positions. I contend that this is a distinguishing aspect.

I regard "common UI elements behave the way they commonly do" as being useful for readers.

Now that's just hyperbolic. Adding a background or border is not meaningfully changing behavior any more than specifying a non-default cursor for <var> elements, and is arguably less of a behavior change than inserting hidden list counters.

[bakkot]

There are lots of long documents on the web with tables of contents? I am confused by the contention that this is at all unusual.

Now that's just hyperbolic. Adding a background or border is not meaningfully changing behavior

The behavior isn't having a background or border. It's making those change in response to clicking on an entry in the table of contents. I'm not objecting to the styling itself (well, also to that, but it's more likely we could find something mutually agreeable there) - I'm objecting to the styling changing when navigating with the table of contents. And that is, to me, a very meaningful (and very distracting) deviation from the common behavior for a table of contents.

[gibson042]

The behavior isn't having a background or border. It's making those change in response to clicking on an entry in the table of contents. I'm not objecting to the styling itself (well, also to that, but it's more likely we could find something mutually agreeable there) - I'm objecting to the styling changing when navigating with the table of contents. And that is, to me, a very meaningful (and very distracting) deviation from the common behavior for a table of contents.

The table of contents itself exhibits the same highlighting behavior, and additionally expands and contracts in response to not just clicking but simply scrolling. The former behavior is not uncommon across the web today (although certainly far from universal, e.g. Wikipedia just added it this year), but it's still rather rare to encounter the latter. How is a static highlight that appears on navigation (i.e., an explicitly requested visual page jump) "very distracting" in the presence of such a dynamic table of contents?

You said above that you are fine with the general concept, but have since introduced a new complaint related to the mode of navigation and are now escalating descriptions of distaste. I strongly value persistence and you strongly value dismissability; I think we can work that out but it now has its own PR #552. This PR introduces disappearing highlights on target references and leaf sections and non-leaf section headings, and I'd be comfortable with pretty much anything (or lack thereof) if there's a path to persistent highlighting (presumably dismissable, to satisfy you). So if you would agree to something persistent, then what tweaks would satisfy you here—and if you wouldn't, then what kind of disappearing highlights could you tolerate?

[bakkot]

How is a static highlight that appears on navigation (i.e., explicitly requesting visual page jumps) "very distracting" in the presence of such a dynamic table of contents?

I'm reporting my experience: I find the styling of the document changing as I use the table of contents to be distracting, and do not find the table of contents expanding distracting. Do you think I'm... mistaken about my experience? Do you think I have direct access to my brain's "what is distracting" algorithm? What would an answer to this question even look like?

I mean, I can make guesses about the source of the difference - my best guess is that the relevant thing is that the highlight applies to the document, which is the thing I'm trying to look at - but I'm really just reporting the fact of my experience here.

You said above that you are fine with the general concept, but have since introduced a new complaint related to the mode of navigation and are now escalating descriptions of distaste.

When I said that I was fine with the general concept I'd only looked at navigating from the references pane. It didn't occur to me that it also applied to the table of contents; as soon as I noticed that I said I didn't like it.

You asked about why I cared and in response I've tried to explain why I cared: it's only "escalating descriptions of distaste" because you explicitly asked me to explain my objection. I didn't immediately jump to "descriptions of distaste" because "I don't like this" usually suffices.

This PR introduces disappearing highlights on target references and leaf sections and non-leaf section headings, and I'd be comfortable with pretty much anything (or lack thereof) if there's a path to persistent highlighting (presumably dismissable, to satisfy you). So if you would agree to something persistent, then what tweaks would satisfy you here—and if you wouldn't, then what kind of disappearing highlights could you tolerate?

Like I said:

• ensure that the table of contents is just navigation and is not also changing the styling of the document (most easily done by restricting the new behavior to xrefs and dfns and similar), and preferably not styling emu-clause etc regardless of how they are navigated to;
• have a background-color highlight for xrefs and dfns and similar which fades out over a couple of seconds (optionally plus some extra logic so that the fade-out doesn't start until the page is visible, for your open-in-background-tab use case);
• and, for persistence, I'm ok also adding a border around focused xrefs and dfns and similar which disappears when those lose focus, and ensuring that they get focus when jumped to.

That is, exactly what the WHATWG specs are doing (plus optionally the page visibility thing).

I don't like the original styling but if you really want something other than just background color we could probably find something else which works. Doing just background color (with the above constraints) would satisfy me though.

I really doubt I'm going to be ok with any option which includes changing the styling of the main document when using the table of contents, whether or not it's persistent. You can suggest such options but I at least can't think of any which I'd be ok with. Like I said, I'm happy to chat sync at the editor call if you'd like.

[gibson042]

Do you think I have direct access to my brain's "what is distracting" algorithm? What would an answer to this question even look like?

Well, yes? For example, I'm distracted by the toolbox popup appearing on hover and covering other text. As for this question, I can think of several kinds of answer:

• "Very distracting was an exaggeration, but it does draw my attention in a mildly unpleasant way that could be mitigated by…"
• "I think the novelty plays a big part but it likely/possibly would slip below that threshold over time."
• "I use dark mode and there's too much/too little contrast."
• "It's the color boldness/large count of affected pixels/prominent shape/magnitude of deviation/etc."
• "It's the abrupt appearance of new visual elements with no/insufficient animation."

I really doubt I'm going to be ok with any option which includes changing the styling of the main document when using the table of contents, whether or not it's persistent. You can suggest such options but I at least can't think of any which I'd be ok with. Like I said, I'm happy to chat sync at the editor call if you'd like.

I am very much in favor of something persistent w.r.t. sections and independent of navigation mode, so I'll try to join the next call.

[bakkot]

"I'm distracted by this common UI element having more visual effects on the thing I'm trying to look at than what I was expecting, based on how said element typically behaves elsewhere" is the best answer I can give you. I don't think it bottoms out in some other reason - the chain of "I find X distracting because it entails Y, which I find distracting [because...]" has to stop somewhere, and as far as I can tell that's where it stops.

[gibson042]

I've updated this PR to hopefully remove the controversial aspects. It now skips the highlight for clause-like elements, makes the highlight persistent when the target has focus and is "simple" (has either no children or only <a> children), and adds tabindex=-1 to <dfn>s so they can be included in that latter category.

[bakkot]

Thanks, this works for me now, modulo technical quibbles.

First, apparently (that is, it appears to me) elements only get focus when navigated to if they have both a tabindex and an ID, which is only ~84 elements in 262. Most dfns don't have IDs (which is maybe a separate issue; they probably should), and emu-xrefs don't have a tabindex. So outside of those 84 elements, the :focus-within rule doesn't do much of anything unless you hit tab (i.e., it does not give you the persistence you wanted).

Second, the behavior when using tab is weird: when you tab away, it flashes to white and then back to full highlight before fading out. Which is a straightforward consequence of the animation rules, but seems like it's maybe not intended? In the recording below I'm refreshing, then hitting tab and shift-tab a couple times.

https://github.com/tc39/ecmarkup/assets/1653598/2ec8a1ae-ac12-496c-99c4-97bb27e1fe65

[gibson042]

First, apparently (that is, it appears to me) elements only get focus when navigated to if they have both a tabindex and an ID, which is only ~84 elements in 262. Most dfns don't have IDs (which is maybe a separate issue; they probably should), and emu-xrefs don't have a tabindex. So outside of those 84 elements, the :focus-within rule doesn't do much of anything unless you hit tab (i.e., it does not give you the persistence you wanted).

Right, that's a concession on my part. I'm comfortable with opting in to xref persistence by hitting tab, and <dfn>s that lack IDs are effectively aliases for their containing clauses w.r.t. references and therefore won't get highlighted.

Second, the behavior when using tab is weird: when you tab away, it flashes to white and then back to full highlight before fading out. Which is a straightforward consequence of the animation rules, but seems like it's maybe not intended? In the recording below I'm refreshing, then hitting tab and shift-tab a couple times.

Addressed that by adjusting the animation to remove the initial ramp up; tabbing away will now fade out just like happens in the absence of initial focus.