Editorial review: Add reading-flow and reading-order docs #39404
Conversation
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
…t into Praveen7294-add-reading-flow-docs
github-actions
bot
added
Content:CSS
chrisdavidmills
changed the title
|
|
||
| The `reading-order` property lets the author change where in the reading order an element is read out or tabbed to. It enables authors to override the reading order set by the [reading-flow](/en-US/docs/Web/CSS/reading-flow) property on its parent. | ||
|
|
||
| The default `reading-order` value is `0` for elements inside a block, flex, or grid container. This puts them all in the same ordinal group. Sibling elements are ordered starting from the lowest numbered ordinal group to the highest. Therefore, to cause an element to be read out after its siblings, you could set a `reading-order` value or `1` or more on it. To cause an element to be read out before its siblings, you could set a `reading-order` value or `-1` or less on it. |
There was a problem hiding this comment.
| The default `reading-order` value is `0` for elements inside a block, flex, or grid container. This puts them all in the same ordinal group. Sibling elements are ordered starting from the lowest numbered ordinal group to the highest. Therefore, to cause an element to be read out after its siblings, you could set a `reading-order` value or `1` or more on it. To cause an element to be read out before its siblings, you could set a `reading-order` value or `-1` or less on it. | |
| For reading and navigation, elements inside a block, flex, or grid container in a container are sorted by ascending `reading-order` value and then by their source code order. Items not given an explicit `reading-order` value are assigned the default value of `0`. This puts them all in the same ordinal group by default. | |
| Sibling elements are ordered starting from the lowest numbered ordinal group to the highest. Therefore, to cause an element to be read out after its siblings, you could set a `reading-order` value or `1` or more on it. To cause an element to be read out before its siblings, you could set a `reading-order` value or `-1` or less on it. | |
| The `reading-order` defines the reading and tabbing order. This property has no effect on visual order. To alter the visual order of items in a container, see the {{cssxref("order")}} property. |
how does this interact with tabindex?
There was a problem hiding this comment.
updated.
As for tabindex, that is a good question — I've tried a bit of experimentation, but found the results a little bit confusing.
@rachelandrew, can you give us a summary of how reading-flow/reading-order interact with tabindex?
There was a problem hiding this comment.
Reading flow containers become focus scope owners. The PR here contains the HTML definition.
I believe this explainer is also correct, but I'd treat that PR as the source of truth,
There was a problem hiding this comment.
This is ... quite complicated. I've done a bit of testing, and from my findings, it looks like the effects of tabindex are pretty much ignored when reading-flow/reading-order are set, and their effects override them. When you set tabindex="0" on a load of items and place them inside a reading flow container, they follow the reading flow set by reading-flow/reading-order. When you try using positive tabindex values, they are basically ignored.
Do you think this is accurate?
I wonder whether it would be good to mention something like this on both pages, say that a bunch of stuff that used to be hacked around using tabindex can now be fixed using reading-flow/reading-order, and follow it up with another reminder not to use positive tabindex values.
There was a problem hiding this comment.
OK, so from reviewing @estelle's tests, it looks like I am right. I'm not convinced we need to add another demo to demonstrate that reading-flow/reading-order overrides tabindex and it is ignored while they are in effect. We should just add some explanation to each page to mention this.
Does that work for you, @rachelandrew, or have I got this wrong?
There was a problem hiding this comment.
that's correct, it essentially overrides tabindex, as if people were using positive values they probably shouldn't be in most cases.
There was a problem hiding this comment.
Cool; I've added a subsection to the "Description" section on both property pages, in my next PR.
files/en-us/web/html/reference/global_attributes/tabindex/index.md
Outdated
Show resolved
Hide resolved
|
I am having issues with the |
|
Inline elements supporting reading-order example: https://codepen.io/estelle/pen/zxGOvLB |
|
I had a few instances where reading-order worked with reading-flow: normal, but now I can't seem to replicate it, so thinking the JS may have been setting the |
| - Reading flow | ||
| - : A modified reading order. | ||
| - Reading flow container | ||
| - : An element with a reading flow set on it. |
There was a problem hiding this comment.
let me know if you want me to create the other glossary page.
There was a problem hiding this comment.
I don't agree with you on this point, but you seem pretty determined about this. Do you think you can do it as a separate PR after this one has been merged, so as not to hold it up?
There was a problem hiding this comment.
Is "reading flow" here the thing that in the spec is called "rendering-defined sibling reading flow" (https://drafts.csswg.org/css-display-4/#rendering-defined-sibling-reading-flow)? Because if so, these definitions seem to be backwards. The spec defines "rendering-defined sibling reading flow" in terms of "reading flow container", but this reverses that, defining "reading flow container" in terms of "reading flow".
Which is a problem, because the only solid (i.e. spec-derived) definition of "reading flow" is in terms of "reading flow container", so you have a circularity.
FWIW I don't think this needs a separate glossary entry, but as it stands, in this glossary entry, it's unclear that these are formal CSS terms, as it goes straight from general prose into this DL, without any context. I think it needs a heading like "Setting reading order in CSS" before it starts talking about the CSS properties, and then a line to introduce these definitions so I know what I'm staring at.
And if we're going to include these as official CSS spec terms, we should be precise about them.
(I think the scroll snap comparison is instructive, and I have the same issues with contextualization there).
There was a problem hiding this comment.
Thanks, @wbamberg. I've read the spec again, and you are right — I did have the definitions the opposite way round. I've modified the definitions so that "reading flow container" is defined first, and "reading flow" is defined in terms of it.
I've also added a heading and a sentence to introduce the terms so that it flows better.
I'm not exactly sure about including the official spec terms in both cases; I mean, the official spec term for reading flow is "rendering-defined sibling reading flow", but I thought that was a bit wordy and unhelpful for the MDN audience, so I chose "reading-flow" ;-)
But yes, I appreciate the need for precision in such a case.
Co-authored-by: Estelle Weyl <estelle@openwebdocs.org>
Co-authored-by: Estelle Weyl <estelle@openwebdocs.org>
Description
Completing work originally started by @Praveen7294 in #38859, on documenting the
reading-flowandreading-orderproperties.See https://drafts.csswg.org/css-display-4/#reading-flow for the specification.
This PR adds ref pages for the two properties, but also updates the CSS Display module page to suit, and adds a glossary entry for "reading order".
Motivation
Additional details
Related issues and pull requests