API to expose the Outline algorithm

robin · 2014-05-21

HTML supports an outline algorithm which is currently supported in a number of tools but not exposed in the browser. Computing outlines can be supported in script, but is easy to get wrong. Would there be interest in adding a method that would expose this information?

The outline is too slow to compute to make this an attribute, but it could be returned by a method on demand.

If this is useful to you, I’d be interested in hearing how you plan to use it so that we can give it the right shape.

SteveF · 2014-05-21

yes and yes. i have envisaged in my limited understanding sort of way a read only ‘level’ attribute for h1-h6 being exposed in the DOM which can be queried by 3rd part tools/scripting. The attribute would reflect the outline depth of the heading.

briankardell · 2014-05-21

To make sure I understand - you are suggesting a read-only method that would return… some new OM?

brucel · 2014-05-21

Related: I’d like some CSS thing like :heading-level(3) that would let me style “logical” h3s. section section h1, section article h1, article section h1, article article h1, nav article h1, article nav h1, article section h1 … etc is a major PITA that bloats stylesheets.

Someone will now tell me such a thing already exists, and I’m a massive fool.

briankardell · 2014-05-21

Related? https://github.com/ThePacielloGroup/w3c-heading/blob/gh-pages/README.md#under-the-hood

domenic · 2014-05-21

Here are some use cases I can think of:

Specs. Pretty obvious; spec preprocessors do this already.
Wikis, e.g. Wikipedia’s TOC.
eBooks, in some form. I’ve experimented with eBooks that are a single HTML file, instead of the industry-standard zipped-up-multiple-XHTML files format. In this case generating the TOC via such an algorithm would be excellent.

In all cases I would probably create a custom element to wrap the imperative API into whatever format is most appropriate for my use case, e.g. trimming off title pages for a book TOC or removing the h1 level for a Wikipedia TOC.

SteveF · 2014-05-21

yes, that is an ongoing exploration of providing a heading feature encompasses the outline concept and how it could/should work

briankardell · 2014-05-21

you’re saying this has been discussed? what the OM looks like and so on? If so, link?

robin · 2014-05-21

It’s sort of a view on the DOM, an object structure which references elements, possibly Ranges covering sections (super useful when there’s no <section>). Nothing radically new

robin · 2014-05-21

I also like the ebook use case a lot, though paradoxically I am still unsure as to <toc> (paradoxically because script-less would be great for ebooks).

There’s a thread on the topic on public-html (who said nothing of interest happened there? :).

SteveF · 2014-05-21

This is related to what have been talking about in a w3c-heading issue. we decided to add a ‘level’ attribute. Not just the CSS case but it helped in deciding.

SteveF · 2014-05-21

From an accessibility layer perspective, there is already a requirement in the spec to implement the outline algorithm as it is needed to calculate a headings outline depth:

required mapping:

hx = heading role, with the aria-level property set to the element’s outline depth.

So if the outline algorithm is required to be implemented anyway, why hide it in the acc layer?

Also note that in practical terms outline depth information needs to be available in the DOM for most AT.

heydonworks · 2014-05-22

I’m imagining something along the lines of the browser “fixing” heading levels in the way they already try to close unclosed elements or add fallback / default attributes.

That way, authors using sections with headings would have the choice of using a generic <h> and styling using something similar to what @brucel suggested (perhaps h:level(2) for second level) or use <h1> to <h6> to determine style (font size, I suppose) and the browser would correct for structure.

The corrected structural info would be forwarded to AT in much the same way as adding aria-level="3" to an <h1> nested three sections deep.

<body>
   <h1>Master Heading</h1>
   <section>
      <h2>Sub Heading</h2>
      <section>
         <h1 aria-level="3">Visually Big Heading</h1> <!-- corrected in DOM -->
      </section>
   <section>
</body>

Am I on the right track?

I’m guessing some correction would be possible without the depth dimension of sectioning elements too. For example:

<h1>Master Heading</h1>
<h3 aria-level="2">Sub heading</h3> <!-- corrected in DOM -->

That is, the next element after <h1> belonging to the array [h1,h2,h3,h4,h5] should be an <h2>.

briankardell · 2014-07-17

Anyone done any work on this? I’m still very interested in what it returns exactly… Is it a new OM? It feels like it is semi-related conceptually (as a general problem that is) to the render-tree in the sense that it is ‘another view on the DOM’ which isn’t historically exposed… I’d like to see more details on what someone is thinking that would look like and how to make it practical/perf - and if it is ‘on demand’ could we prollyfill it along with spec’ing it out.

sideshowbarker · 2014-07-17

I’m not really sold on Robin’s “view” idea. I’m not sure we need this to be any more complex then just, we expose a way to create a static outline on demand, which consists of an “Outline” object that’s just a tree of “Section” nodes—where the spec would need to define what a Section node is (simple to define), and from that define what an Outline is (even simpler to define).

For an existing JS implementation that pretty much does exactly that, see Dominykas Blyžė’s h5o HTML5 outliner code, in particular, his code for the HTML5Outline(*element*) method here:

https://github.com/h5o/h5o-js/blob/master/src/HTML5Outline.js

But if we were to standardize it, I think that instead of that approach, it should just be a new method for HTMLElement, so that you could just create an Outline object with element.createOutline() (so, with no args needed).

However I wouldn’t object to instead just exposing it as a standard document.createOutline(*element*) method (i.e., basically just what Dominykas’s HTML5Outline(*element*) method does.

Implicit in all that of course is that we’d want to provide developers with the flexibility to create an outline not just for the entire document, but from any arbitrary subtree of the document, with whatever element they want at the root of the outline.

briankardell · 2014-07-17

So, based on that, I believe you’re suggesting it would return an OM like so… ?

madcampos · 2014-09-05

I like the idea and as my suggestion it would be a method like: element.outline() and would return a token list containing the html elements or another token list for the next depth. Just this simple as it’s lightweight and authors could write on top of it.

From the css perspective it could be a @oultine-level(n) directive that we could style just like a media query, and as such cascade to grather depths.

A use case for this could be a wiki with a toc (generated), some content aside and a few levels of depth in the document. in this example the toc could have one style, an aside with metadata another, aside images and quotes yet another style and references a different one. The wiki “chrome” could still be also rendered in another way separated from it’s content.