Consider adding a headinglevelstart attribute #5033
Comments
annevk
added
addition/proposal
|
Reading through the other thread, I'd prefer this approach of an opt in instead of just overwriting heading levels. The only question I have is what is the expectation for something like: <h1>GitHub</h1>
<h2>jsdom/jsdom</h2>
<div>
<article headinglevelstart="5">
<h1>jsdom</h1>
<h2>Basic usage</h2>
<h2>Customizing jsdom</h2>
<h3>Simple options</h3>
...
</article>
</div>Expose h5, h6, h7 instead? h7 obviously being the outlier here. Quickly looking at some of the different exposed levels from the platform mappings / trees exposed by browsers, a level 7 should work, but JAWS and NVDA range from getting a little tripped up at times, to JAWS with Firefox just not exposing the levels beyond 6 at all, instead reverting to level 2 or the default level of the heading element used. Again, it seems the screen readers would need to be updated to account for heading levels beyond 6. Unfortunately, that also means that anyone using an older screen reader, even with a newer browser, may well not get optimal output. |
|
This would solve all my problems with hN tags: user/plugin generated content in templates and template partial that use hN tags. The template including any of the above can just tell it where to start. |
|
If an author can identify what value needs to be set in Pseudo-code with structure borrowed from above: In other words, the For example, in this Codepen example from 2016 I use Though neither approach prevents an author from choosing a value that renders as |
|
@aardrian wrote:
The priority of constituencies puts users and authors before implementors, and this seems to be one of the times when that prioritisation is needed. Authors struggle with heading levels as it is, and this has an impact on users. If we ask authors to take on handling more, I'm afraid things will only get harder for authors and worse for users. If the UA does the work, it has other advantages too:
On this last note, would it be possible to extend the capability of the |
I like how short the "start" attribute is but if it only contains a number in it, it isn't as clear what it is doing as it is on ordered lists. If you have |
In fairness, from a development point of view, using without having to server-side re-munge the content to reprocess all heading levels appropriately. Otherwise, particularly for third-party stuff, they'd have to always proxy content and do, in naive terms, do a find/replace of any heading elements (either native |
|
@LJWatson, to your point about the Priority of Constituencies, I feel that pushing the logic to the UA creates a black box that will make it easier for developers to ignore, resulting in a generally worse experience for users. And I also want a better experience for users (over authors). @patrickhlauke, that is a good point (and also made by @LJWatson). And yes, the client-side processing is potentially more burden for users than broken / opaque headings. Perhaps something similar to the code/approach I posted above could be the basis for a polyfill (though it still won't help current SRs). |
|
This mostly addresses what I was interested in in this comment a while ago - though, it still seems to me we could probably just figure that out with simply a marker attribute rather than an explicit level, and that would be better for authors. Still, this very much seems like progress and worth doing if that's not plausible. |
That is simple for simple cases but it gets more complicated quickly. The approach you outlined works fine within a single template file whose content is all under the control of the author (but, in that limited context, so does just using h-tags, which are also easier to read). Here is where it hurts: When a template includes another template the counter needs to be both threaded through the template and used by the child templates as well. Many templating languages support this, though not all make it super pleasant, but it's not of much use unless the entire project agrees upon the convention. That's easy on greenfield projects but legacy code requires more work or when there's a "parent theme" and you end up needing to modify all of its templates even if you're making no other changes. On hosted platforms the choice of templating language is usually fixed so whether this can be done at all can be out of one's hands. Sometimes html comes from a blackbox plugin. This is no one's favorite but it happens distressingly often. The generated html can be parsed and its headers shifted by walking the AST allowing it to be re-rendered correctly, but this is fairly complicated and slow so it's unlikely to happen and probably needs to be fixed up on the client side with some javascript. If the platform had the concept of the heading level baked into its core and took care of threading it through templates and plugins, all of which agreed to use this feature, this wouldn't be as much of an effort. To my knowledge, there is no such platform or at least it is not among the most commonly used. Even if all the popular ones added it today it would take quite a while for it to see widespread use and for legacy code bases to get on board even if their platform now supported it. That still leaves user-generated content. If it's stored in some non-html source or some IR that can make it easy to generate starting at whatever level is necessary (assuming it's an option: it usually is not). Often it's stored in html that was created by some kind of WYSIWYG editor. If every instance of the user generated content starts at, say, h2, you could configure the header to not allow creating h1 tags. If this is a legacy project or a project going under redesign that means going through the database and parsing all the entries and shifting the headings. Not pleasant but it's a one time thing. If you're trying to use the content where the starting header is different in different contexts you're back to fixing it up on the fly. (I haven't looked into it too deeply yet, but it seems like wordpress's gutenberg would have many of these problems simultaneously). None of this is insurmountable but it's enough to surmount that it doesn't seem to ever get surmounted. Having an attribute may mean occasionally having to add a div to hang it off of but the outlining solutions could also mean having to insert an extraneous tag and generally one of greater semantic weight and its less explicit that those tags are necessary to maintain the correct document outline. An attribute would also make it easier to fix up a legacy codebase with just a few simple edits. Another thing I like about having an attribute is that it could possibly have extra modes in the future like "none" to mean "ignore any headings in this subtree" (useful for teasers whose teased body should not be contributing to the document outline) or something to mean "this came from an editor apply a slower algorithm to shift the headings so that are no gaps like h3 to h6 with no intervening h5". |
|
@jimmyfrasche, I feel bad that my response is so brief as to seem dismissive, but I understand your points and agree with many. After my last comment I am not pushing my model anymore as I made my case (and nobody seems down with it). But I still think a polyfill may be helpful. |
|
Notes from TPAC, slide for context. What this proposal do: help web authors prevent user generated content from breaking the page heading structure. To clarify, this is the expected affect: Code <h1>jsdom/jsdom</h1>
<h2>Files</h2>
<h2>README.md</h2>
<div headinglevelstart="3"><!-- user generated content starts -->
<h1>jsdom</h1>
<h2>Basic usage</h2>
<h2>Customizing jsdom</h2>
...
</div>
<h2>About</h2>
<h3>Resources</h3>
<h3>Licenses</h3>
<h2>Releases</h2>
...Heading structure h1 jsdom/jsdom
h2 Files
h2 README.md
h3 jsdom
h4 Basic usage
h4 Customizing jsdom
h2 About
h3 Resources
h3 licenses
h2 Releaseswith an addition to the proposal: interface HTMLHeadingElement {
[CEReactions] readonly attribute unsigned long level;
};In case of <div headinglevelstart="2">
<article headinglevelstart="6">
<h1><h1>
<h2 aria-level="1"><h2>
</article>
</div>$ h1.level // AAM level 7
7
$ h2.level // AAM level 1
8
$ h2.ariaLevel
1Todo:
Future to do:
|
|
Also discussed at TPAC: need to define how this works with Shadow DOM. Most like the level should be computed based on the shadow including ancestor chain. |
|
For a lot of use cases, this will probably be fine as long as the headings remain in the 1 to 6 level range. But things are slightly better than I mentioned 4 years ago with browser/screen reader support for levels beyond 6. Safari and Firefox expose the specified level if one goes beyond level 6, but Chrome/Edge appear to cap out at level 9, and beyond that heading levels get exposed as a level 2 regardless of the specified value. Vispero/JAWS would need to be looped in on this, as levels beyond 6 get treated as level 2 - regardless of if the browser exposes the specified level or not. I also noticed that NVDA doesn't include headings between 7 and 9 when navigating with the H key with Chrome, but seems to do it fine with Firefox. So, also something they should be looped in on, as well. I mention all of the above specifically in context to:
Since a polyfill won't be enough without Chrome and Edge/UIA being modified to expose levels beyond 9, and JAWS changing their treatment of higher levels. Fairly recently, the Editor's draft for ARIA included this note for
The important part of that note - as support for higher levels can obviously change with work - is more the fact that the higher the potential heading level, the more difficult the content may be to understand/navigate for someone using a screen reader. So with that said, I'm supportive of the intent behind this attribute and how it can make heading levels easier to adjust for developers when necessary, but was there any talk of a level cap for this attribute at TPAC? Making sure all browsers/screen readers support up to level 9 seems reasonable. That's at least what the ARIA wg discussed when creating that note. But beyond level 9 maybe seems a bit much? Someone being able to declare |
I suspect that as soon as you introduce a reasonable-sounding cap, somebody will come along with a particularly complex document/site that requires one more than the cap... |
|
I mean, they must be getting by somehow right now, with their six-level limitation, though maybe they're not. so yeah, that's fair point @patrickhlauke. Author guidance to allude to the potential cons then, at least? |
Yes, @mcking65 and @spectranaut was at the WHATWG meeting. Matt brought up exactly this issue. I am personally not opposed to capping the levels but agree as @patrickhlauke said. The level problem was why future to do (as author guidance) was included, since user misuse of the attributes (
Happy to add a cap in a draft spec, but regardless I hope it won't block this proposal, as for the alternative seems to be what led to this proposal to begin with 🙈 .
FWIW my plan was to leave this up to further feedback when I create the polyfill, with capping at 6 or 9, or none. |
|
thanks @muan - yeh i saw the 'future to do', but i would just submit that author guidance should be added with the proposed spec update and also keep the future to do for checkers to consider adding guidance as well. Whatever guidance is added would be contingent on the decision to cap or not, but that shouldn't be a blocker. |
|
I've initialized a polyfill with some open issues. Feel free to open issues and let me know if you'd like to be a contributor! I'll carry on with the rest of the to-dos. |
Does not seem that Firefox & Chromium have any inherent CSS formatting for
|
|
@tomByrer FWIW with this proposal there is never going to be for styling @annevk had previously suggested a functional pseudo-class selector. |
|
I think we should add |
|
Would <div headinglevelstart="2">
<h1>Hello</h1>
<div headinglevelstart>
<h1>World</h1>
</div>
</div>Where |
Why only up to level 9? I see having a limit of any kind as an unnecessary restriction on what authors can implement in their layouts. |
|
I think we're saying the same thing but in slightly different ways. Let's start with one <div headinglevelstart=4>
<h1>aria-level=?</h1>
</div>
We do want to think of this in terms of sums but Let's add the second layer back in: <div headinglevelstart=2>
<h1>aria-level=?</h1>
<h2>aria-level=?</h2>
<h3>aria-level=?</h3>
<div headinglevelstart=4>
<h1>aria-level=?</h1>
</div>
</div>for the first three tags we have If we don't consider nested However if we sum all the ancestral If you remove the outermost |
|
Specifically, this is the example of nested contexts I gave, where you pretty clearly (imo) need the level changes to be "local". So in the example code being worked with here, I feel fairly strongly you should get: <div headinglevelstart=2>
<!-- aka, interpret contained <h1>s as if they were an h2 in the outer context,
and lower headings adjust accordingly -->
<h1>aria-level=2</h1>
<h2>aria-level=3</h2>
<h3>aria-level=4</h3>
<div headinglevelstart=4>
<!-- aka, interpret contained <h1>s as if they were an h4 in the outer context (now h5 in the global context) -->
<h1>aria-level=5</h1>
</div>
</div>Instead writing these as (In either case, tho, making the value relative to the nearest ancestor The only issue with the above (with either spelling) is that you must set the value on the outer template, as you need to know precisely where in the outer template's heading structure the inner template is being placed. I think this is acceptable, fwiw, but if we did want to allow the inner component to opt itself into heading adjustment instead, we would indeed need an |
|
Maybe |
|
So @smockle and I at GitHub are prototyping this out (https://groups.google.com/a/chromium.org/g/blink-dev/c/8yl-pJhuLHE/m/1GDufCYWAAAJ). We have some various points to raise and discuss. The devil, as the say, is in the details. Any opinions weakly held, we'd like to hear feedback from y'all. Naming
After further discussion below, MicrosyntaxesRight now we have implemented the IDL to reflect long values, likely "limited it to only non-negative numbers" as it seems something like This means you can put in Additive ModelThere's been a lot of discussion about an "additive model" (where multiple containers accumulate) vs "absolute" (find the nearest and use that value). From an implementation standpoint either model is trivial (we tree walk, and we either stop at, or accumulate, on each node with the attribute). The real decision here is picking one and sticking with it, as it's not a decision that will be easy to change once implemented. We went with the additive model during the prototype as it feels like that has more implications that need testing; the perf impact, the complexity on web developers side of things. This means the following: <div headingoffset=1> <!-- h1s are now h2s and so on -->
<h1><!-- Level 2 --></h1>
<h2><!-- Level 3 --></h2>
<div headingoffset=2> <!-- h1s are now h4s -->
<h1><!-- Level 4 --></h1>
<h2><!-- Level 5 --></h2>
</div>
</div>An auto valueAuto values have been discussed. There are some large concerns on our side with this. One path is that <div headingoffset=auto>
<h1><!-- Level 1 --></h1>
<div headingoffset=auto>
<h1><!-- Level 2 --></h1>
</div>
</div>The issue is that for simple demos this looks fine but it gets a bit funky if you have real outlines: <div headingoffset=auto>
<h1><!-- Level 1 --></h1>
<h2><!-- Level 2 --></h2>
<h3><!-- Level 3 --></h3>
<div headingoffset=auto>
<h1><!-- Level 2 --></h1>
</div>
</div>This feels broken from an AT user perspective because they're not traversing down a heading structure, in fact it feels like not much of an improvement at all. Consequently, it feels like we'd want <div headingoffset=auto>
<h1><!-- Level 1 --></h1>
<h2><!-- Level 2 --></h2>
<h3><!-- Level 3 --></h3>
<div headingoffset=auto>
<h1><!-- Level 4! --></h1>
</div>
</div>This worries us from both a complexity and performance perspective. Effectively auto would need to span its descendent tree and find the largest heading element. Perhaps more experienced spec authors/implementers can tell us how actually troublesome this would be but our hunch is that it's not great. What to do about aria attributes?We feel fairly strongly that <div headingoffset=4>
<h1><!-- Level 5 --></h1>
<h1 aria-level=1><!-- Level 1 --></h2>
</div>What's slightly less clear is what to do with a <div>
<div role=heading><!-- Level 2 --></div>
</div>What happens if we introduce a <div headingoffset=1>
<h1><!-- Level 2 --></h1>
<div role=heading><!-- Level 3 --></div>
<div headingoffset=2>
<h1><!-- Level 4 --></h1>
<div role=heading><!-- Level 5? --></div>
</div>
</div> |
|
Thanks for moving this forward! Some thoughts:
(Overall, I'd probably stick with additive, using ordinary HTML integers, and drop auto and ARIA integration.) |
+1. Adjusting the naming with something like shift/offset seems good. |
Yes that's understood. I think we went in this direction. We assessed if auto would be a good option, counted it out due to complexity, then realised without auto we could simply reflect a value as long which makes the implementation far simpler. I think if there's strong desire for
Sounds good to me, if it sounds good to Jake too.
That sounds like a good idea. We'll move forward under the assumption that this only impacts
👍
👍 in which case we'll rename to |
Yeah, I only used the + to differentiate between absolute values and relative values. If it's always additive, and is named to suggest that, it's good. |
|
FWIW i have a slight preference for |
|
It seems to me that if we have an additive model it is at least plausible to build new documents which follow a relatively simple strategy that affectively gives them an 'auto' value, but doesn't try to solve the (probably impossible?) task of making it possible to just slot that automatically into any existing document with messed up headings strewn all over the place. I am supportive of trying the additive model and I like both of the named versions being supplied above, and also have a (very) slight preference for |
|
thanks @keithamus (and all who have helped work on this!), this looks promising! @annevk beat me to it, but absolutely agree that |
|
For me the frustration that I hope this proposal will solve is headings in components. If you want to define a reusable part, sometimes that includes a heading or two. But it becomes a whole thing because as the author of the component you do not know where it will be used. So you have to build a way to deal with the headings to fit where it'll end up in the hierarchy, or give up on the whole idea. It would be awesome if the browser could figure that out automatically. If that requires a property, that's fine. An auto value would be excellent, because you can just set it as the component author. If 'auto' is problematic for some reason, I guess it's okay if the user of the component has to set a specific offset value, but it has the disadvantage that it can be forgotten. With regards to aria headings, why would they be treated any differently? A div with role heading and aria-level="3" is functionally an H3, so I'd expect it to be affected similarly. So in the odd situation where the aria-level is not provided and it defaults to an H2 like thing, why not treat it like an H2? You're explicitly opting in to the heading recalibration with the attribute, so it should not be surprising that it becomes a different level heading. The one other thing I'm worried about is going beyond H6. With this attribute, it'll become very easy to recalibrate a heading to a level beyond 6. I believe the JAWS screen reader handles up to 10, anything beyond that will effectively become an H2, completely screwing with the heading structure. If I remember correctly NVDA ignores everything beyond 6. I think this proposal should include what should happen if the headings go beyond 6 (and 10). While in websites you don't often go that deep in the heading structure, In more complex web applications it is not uncommon to have to have hard discussions about how to stick within the 6 available levels. Once you can add headings into components because you can offset them, it becomes a even harder to keep this under control. |
I am a humble facilitator. Credit goes to @muan for the proposal, everyone here for the wonderful discussion and @smockle for prototyping!
In theory that's possible with this proposal I believe. If each component started its own heading outline with level 1, and set the containers it rendered its components into with a headingoffset appropriately scoped, then everything should flow. The main document would then also need to set the appropriate attributes as it incorporates headings. <body headingoffset=0><!-- redundant, for illustrative purposes -->
<h1>My wonderful component based website</h1>
<my-component headingoffset=1>
<template shadowrootmode=open>
<h1>This is an h2</h1>
<sub-component headingoffset=1>
<h1>This is an h3</h1>
</sub-component>
</template>
</my-component>
</body>
I think this logic is reversed from reality. All headings are functionally identical aside from their localname, which is used to derive the level they expose to AT. In other words an
Right now our prototype implementation clamps to a maximum level of 9. So |
|
In your additive model example, you have the following: <div headingstart=+2> <!-- h1s are now h2s and so on -->
<h1><!-- Level 2 --></h1>
<h2><!-- Level 3 --></h2>
<div headingstart=+2> <!-- h1s are now h4s -->
<h1><!-- Level 4 --></h1>
<h2><!-- Level 5 --></h2>
</div>
</div>I don't understand this example - did you mistype some of the numbers? Your outer container has I presume you meant that, in the outer container, h1s become h3s, and in the inner, h1s become h5s, right? Or perhaps you meant for the outer container to have |
|
Yes sorry the example's first heading start should be <div headingoffset=1> <!-- h1s are now h2s and so on -->
<h1><!-- Level 2, h1 + 1 = 2 --></h1>
<h2><!-- Level 3, h2 + 1 = 3 --></h2>
<div headingoffset=2> <!-- h1s are now h4s -->
<h1><!-- Level 4, h1 + 2 + 1 = 4 --></h1>
<h2><!-- Level 5, h2 + 2 + 1 = 5 --></h2>
</div>
</div> |
|
The problems we face building components and themes for a CMS are:
To me it seems that this proposal only helps with problem 3. <!-- we know this h2 is correct in this location -->
<h2>Some title</h2>
<div class="a-slot" headingoffset=2>
<!-- we don't know anything about this -->
{{ content }}
</div>But it doesn't really help with the first two right? Example: <!-- this h3 was set by an editor and is unknown to us when writing code -->
<h3>Some title</h3>
<!-- this is component code we write -->
<!-- which offset do we use so that it is a part of the current chapter? -->
<div headingoffset=??>
<h1>Other title</h1>
<!-- component -->
</div>I might be overlooking something in the latest proposal that does help with these issues? |
|
@romainmenke The proposal enables an author who uses your component to wrap the component in an element with an appropriate I don't think that getting the heading structure correct reliably is possible without an explicit statement from the author or a requirement for explicitly marked sections. Without it we can't know whether the component in an example such as <h2>Section heading</h2>
<h3>Subsection heading</h3>
<p>Paragraph</p>
<the-component>…</the-component>is intended to be inside the implicit subsection marked by |
|
I think you're right @romainmenke - if you plan on interleaving components within unknown content you'll need to somehow determine the heading level used in the unknown content. I'm not sure how this can be solved without ratcheting up the complexity, and I'm cautious that we definitely don't want to repeat the ill-fated document outline algorithm. |
|
The interleaving of unknown components is the direction that CMS's like WordPress have chosen. Given how much of the web is powered by these CMS's I do think it is important to try and solve it for these aswel. But I appreciate that this implies significant complexity :) |
|
I think it's important to de-scope that kind of work for the initial prototype due to the complexity. We can always come back and add something like |
|
Agreed. I think the best answer here is for WordPress to have a plugin to fill in the right value of (that doesn't mean there can't be a more complex feature later that removes the need for that plugin) |
Do you mean that a plugin (or any custom code in any CMS) provides some input field and that content editors set the right value? If so, yes, I think that is the only viable way to use This could be paired with tools that show a more abstract document outline, like the Accessibility Tree view in Chrome dev tools. Content editors wouldn't need to know exactly how Giving content editors the tools to set the value and have good feedback on their document outline already helps end users a lot. |
|
It's been a while since I worked on a CMS so I didn't want to speak outside my experience but my imagination is that if the thing we labelled as "unknown content" is actually content within a WYSIWYG editor within the CMS then it seems plausible for the CMS to, when a component it added, resolve the documents outline and inject an applicable |
|
Things like Gutenberg (the thing replacing TinyMCE in WordPress) allows you to nest components. So you might have a Keeping track of the last used heading level is also something I am considering but I think it will require re-parsing all preceding content. Any component can render whatever HTML it wants. There isn't a hard requirement that they must use a specific function to render headings or that they must trigger a callback. The only way to determine the previous heading with certainty is by buffering the output and re-parsing it. Exposing |
|
One potential gotcha with a cumulative <main headingoffset=0>
<h1>Settings</h1>
<section headingoffset=1>
<h1>Profile Settings</h1><!-- this is effectively h2 (1+1) -->
...
</section>
<section headingoffset=1>
<h1>Account Settings</h1><!-- this is effectively h2 (1+1) -->
<button invoketarget=delete_dialog>Delete my account</button>
<dialog id=delete_dialog>
<h1>Delete Account - Are you sure?</h1><!-- this is effectively h2 (1+1) -->
<form method=dialog>
<button type=submit>Yes</button>
</form>
</dialog>
</section>
</main>In this example, ideally the content structure would be h1 "Settings", h2 "Profile Settings", h2 "Account Setings", and the Potential solutions?Unfortunately because Stop TagsAllow elements to stop the tree walk - so if the check sees a let node = this;
let offset = 0;
while (node = node.parentElement) {
if (node.localName == 'DIALOG') break;
offset += node.headingOffset;
}Of course the downsides here are that the Stop AttributeAdding a The downsides being that it's more markup to undo stuff that was already added via markup. Allowing negative headingoffsetWe could allow negative offsets to undo the shift from other elements. In the above example The downsides are more markup, and arguably more confusing markup, as well as this potentially not really solving the problem. The desire here is to reset the headingoffset to Go back to absolute
|
|
For a modal dialog I don't see what would be gained by doing anything other than always resetting to 0 and I can't think of other places where you would want to do that. Is it possible to just special case modal dialogs? Alt: add |
|
As a reminder, if we do something special for the |
|
Seems reasonable to have a |
and others
See the suggestion by @muan at #3499 (comment):
cc @whatwg/a11y
The text was updated successfully, but these errors were encountered: