Add support for CSS reading-flow

[dizhang168]

The CSSWG resolved to add the new CSS property reading-flow: (https://github.com/w3c/csswg-drafts/issues/7387, spec). Chrome has been working on a prototype for how to change the sequential focus navigation order within a container that has reading-flow. This PR specs the new CSS property reading-flow per proposal described at https://github.com/whatwg/html/issues/10407.

• [ ] At least two implementers are interested (and none opposed):
  • Chrome
  • Gecko: https://github.com/mozilla/standards-positions/issues/1056
  • WebKit: https://github.com/WebKit/standards-positions/issues/378
• [x] Tests are written and can be reviewed and commented upon at:
  • wpt/focus-navigation/reading-flow/tentative
• [ ] Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/issues/40932006
  • Gecko: TBA
  • WebKit: TBA
• [ ] MDN issue is filed: …
• [ ] The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

/index.html ( diff ) /infrastructure.html ( diff ) /interaction.html ( diff ) /rendering.html ( diff )

[domfarolino]

By the way, in the OP you have "At least two implementers are interested (and none opposed):" checked, but neither of the two linked standards positions have been resolved yet, so I'd uncheck that unless you you have other cross-browser support to point to.

[dizhang168]

Thanks for the first pass!

By the way, in the OP you have "At least two implementers are interested (and none opposed):" checked, but neither of the two linked standards positions have been resolved yet, so I'd uncheck that unless you you have other cross-browser support to point to.

Thanks for the call out. There has been conversation in meetings and implementers from non-chromium browsers are interested and none opposed. But I will wait for their comments on the official position issues before checking the checkbox.

[dizhang168]

Status update: I have addressed all the formatting comments. @domfarolino and other reviewers proposed more suggestions and changes at TPAC 2024. I will go back to working on the proposal before making more changes to this spec PR.

[dizhang168]

Thanks for the feedback. I will update this spec to remove any specific CSS properties and instead refer to CSS Display 4 for rendering-defined sibling reading order and reading flow container.

Next, I will refactor this PR accordingly to have only the reading flow order in the context of a focus navigation scope and illustrate the steps with a detailed example.

[dizhang168]

I have updated the PR with a thorough example for the reading flow order algorithm without referring directly to any 'reading-flow' property. Would appreciate your review, thanks. @domfarolino @annevk @emilio

Note: I am working with @rachelandrew to update the definitions in css-display-4.

[annevk]

@domfarolino I would look at blame to see who introduced the naming and ask advice from them. I don't have a good intuition as to what's best here.

[dizhang168]

Re comment: https://github.com/whatwg/html/pull/10613#pullrequestreview-2465972149 I looked at the blame and the definition of "tabindex-ordered focus navigation scope" was added in https://github.com/whatwg/html/pull/4735 by @rakina and reviewed by @domenic

IMO, the naming suggestion makes sense.

[fantasai]

I would like to discuss this one more time briefly during the CSS + WHATWG call. In particular to better understand the stability of this feature on the CSS side.

The stability of the feature on the CSS side shouldn't matter, ideally, because the HTML spec is written in a way that doesn't care how CSS defines the reading order. It should only depend on the idea that CSS can define a reading order that differs from the source order. In the case where these orders differ, HTML needs to define what happens.

If CSS is not imposing a different order, then there should be no behavior change from what happens today.

If we take that as a given, I don't understand why we are importing so many concepts from the CSS spec, and making steps in the HTML algorithm conditional on those...?

[css-meeting-bot]

The CSS Working Group just discussed Add support for CSS reading-flow.

The full IRC log of that discussion

<keithamus> Di: since tpac we've had good conversations on how to handle cases for reading flow
<keithamus> Di: we defined what a scope owner is and so forth. Today is to clarify what we leave to css and what we leave to html
<keithamus> Di: most of the traversal logic is in html spec. We're fetching the css display spec to determine container and reading flow sibling for elements
<keithamus> ack keithamus
<astearns> ack fantasai
<keithamus> fantasai: why are there so many dependencies on the css spec? AFAICT the only thing the html spec needs is css definition of order?
<keithamus> fantasai: what are the behavior differences on something having the reading-flow property?
<keithamus> Di: we don't depend that much on css. We are describing a list of nodes already ordered by reading flow and establishing that on the html side
<keithamus> masonf: the dependencies are as expected: what is a reading flow container and what order
<keithamus> fantasai: what is a reading flow container?
<keithamus> Di: flex or grid container and the order of grid rows and columns and such. We need it so we can switch into a different mode
<keithamus> fantasai: we should have as a principle if the reading flow does not change the ordering of the container it should be a no-op. If I set reading-flow: flex-flow and the order of my layout matches source ordering it shouldn't impact html algorithms
<keithamus> fantasai: you're saying if I set it and it matches the order will be different?
<keithamus> annevk: there is an impact on tab index if its set
<keithamus> annevk: tabindex is scoped to the container
<keithamus> fantasai: if we're introducing a feature for scoping tabindex we should do it where we dont have to flip on one of these other things; it shouldn't be a side effect of grid layout following visual order
<keithamus> annevk: this is the only case where we need it; for now they're coupled. maybe in the future they can be uncoupled
<keithamus> masonf: the reading-flow property adds new behaviors for tabindex, it's a focus scope, it scopes tabindex, it turns on a set of behaviors by using it
<keithamus> fantasai: that behavior should be available without having to change the order; you shouldnt have to change your ordering to get that
<keithamus> astearns: that's separate from the issue of how to spec?
<keithamus> fantasai: then you have two contexts; one is the creation of tabindex scoping the other is css providing a different order for children than you had original
<keithamus> annevk: we dont want one without the other
<masonf> q+
<keithamus> annevk: once you have the container - the container is telling us css is doing something to the children
<keithamus> annevk: its not clear we want to impact tabindex independently from that
<astearns> ack masonf
<keithamus> masonf: the tabindex part of this is to avoid breaking the feature. tabindex messes up the focus order in specific ways. Confusing situations bouncing between containers
<keithamus> masonf: I dont think this is a tabindex feature - it's fixing broken behavior when you're using this feature
<keithamus> fantasai: I feel uncomfortable with turning it on and it not being a no-op when its the default order. it shouldn't impose additional behavior, ideally.
<masonf> You can already scope tabindex with shadow dom or iframes or...
<keithamus> fantasai: secondly if there is scoping of tabindex I think that might be what people want for other purposes but they shouldn't need to change how their items are ordered in order to get that
<keithamus> fantasai: if that seems like something people want to do
<keithamus> annevk: generally tabindex is a misfeature, Im not sure how much we want to build upon it. We just need to handle it
<keithamus> masonf: iframes, shadowdom, slots, all create tabindex focus scopes
<keithamus> fantasai: they require changing your html. It's not just "add this extra attribute or container", the document needs restructuring
<keithamus> masonf: that's true but then we fall back to annevk's argument of this is a misfeature
<masonf> q+
<keithamus> fantasai: I don't think we should introduce a new mode for tabindex solely as a side effect that does something different
<lwarlow> q+
<fantasai> s/that/of something that/
<keithamus> astearns: it sounds to me like this is a necessary side effect for the reading order property, so we have to include it
<keithamus> astearns: but I'm not sure if it's worth making a separable feature if the use cases aren't justified
<astearns> ack masonf
<keithamus> masonf: tabindex is a misfeature and a footgun. The reasons we had to make this a special feature is because otherwise it becomes worse than the existing footgun. This is to protect users from really bad things, not a "oh look here's a cool new feature".
<rachelandrew> +1 to masonf, if we make it a feature it's like we're suggesting people use it.
<keithamus> fantasai: the tabindex is whatever numbers they are inside that element, you never jump in and out of the element? It doesn't interleave?
<keithamus> masonf: correct, it keeps you jumping between reading flow items
<keithamus> masonf: the UA has put them nicely for you in the correct order, but tabindex might mess up the ordering in very confusing ways, including perhaps loops
<astearns> ack lwarlow
<keithamus> lwarlow: I don't fully know the ins-and-outs but my understanding is that it's not doing something completely different to changing tabindex? It changes the way tab works - tabindex is defining the ordering within the source; reading-flow is saying to ignore the source and do something else. So it doesn't seem completely unrelated.
<keithamus> lwarlow: it seems logical that my source code is now being ignored for a visual order. That's just my perception
<keithamus> fantasai: I understand if reading flow says you're going to ignore the tabindex because css is overriding it. I also understand if we say that reading-order is a new source order, and tabindex operates on top. But scoping tabindex in this new way when css defines a new reading order feels off
<keithamus> masonf: how would you avoid the footguns then?
<keithamus> fantasai: can you give me a concrete example?
<keithamus> masonf: a local loop; tabindex jumps you to another item and you jump back to the one before.
<keithamus> fantasai: that's an abstract example
<keithamus> q+
<keithamus> annevk: the other thing was - in order to land this in the html spec the css side needs to be ready. Is it in a WD, is it in review? Is it going to be renamed? What's the stability
<keithamus> fantasai: we don't have a FWPD of the display module. Issues raised against it are not insignificant. I dont know if that'll result in changes to syntax or two different values or something like that.
<keithamus> fantasai: I wouldn't qualify it as solid/ready to ship
<keithamus> fantasai: how much will it change? I don't know
<keithamus> astearns: we should prioritise FPWD
<keithamus> fantasai: interaction with html though - we can basically say there's going to be one or more properties in CSS that can change the desired reading order of a set of children of a box.
<keithamus> annevk: presumably of a node? Like an element?
<keithamus> fantasai: an element
<keithamus> fantasai: and css will define an algorithm going from source order to reading order
<keithamus> annevk: html has that with the container thing... anyway I think I agree. A good next step for this feature to focus on
<keithamus> keithamus: why not ignore tabindex in reading-flow?
<keithamus> annevk: we ignore it on the container but it makes sense for it to be preserved in children
<keithamus> astearns: it sounds like we need more discussions on how scoping tabindex works, and not doing it causes problems. We'll go back to CSSWG to work on the draft.
<keithamus> annevk: when you reference the issue - the html PR is not the issue it should go

[annevk]

Adding "do not merge yet" until we have confirmation that the CSS side is table.

[dizhang168]

CSS side is stable and the FPWD for CSS Display 4 is expected to be published this week. https://github.com/whatwg/html/pull/10613#pullrequestreview-2468472784

Edit: Linked the wrong comment: https://github.com/w3c/transitions/issues/685#issuecomment-2548285397

[annevk]

My best understanding is that the CSS WG does not consider it stable. That's what they also said during the last joint meeting.

[dizhang168]

Sorry, I realized I linked the wrong comment previously. My understanding is that the CSSWG discussed the topic last week and resolved that the CSS Display level 4, which includes the spec for reading-flow can move to FPWD: https://github.com/w3c/csswg-drafts/issues/6900#issuecomment-2536613628 As such, it has been reviewed and should land for December 19, this week: https://github.com/w3c/transitions/issues/685#issuecomment-2548285397

Further, as fantasai mentioned above, "The stability of the feature on the CSS side shouldn't matter, ideally, because the HTML spec is written in a way that doesn't care how CSS defines the reading order." This is true since all we do is reference the concepts of "reading flow container" and "rendering-defined sibling reading flow" from the CSS spec. Tabindex and focus navigation scopes are all HTML concepts. I believe we can remove the label "do not merge yet" and this PR is ready as is.

[rachelandrew]

The spec is now published on TR https://www.w3.org/TR/css-display-4/ my understanding is that the outstanding CSS things to discuss shouldn't impact the HTML side, as Di mentioned in her comment.

[domfarolino]

RE https://github.com/whatwg/html/pull/10613#issuecomment-2552750596: this is great to hear! I'll remove the do not merge label from our end, given that update.

[annevk]

My understanding is different and I'd appreciate it if you could leave the label intact.

[rachelandrew]

@annevk can you explain what you are concerned about (and the relationship to the HTML spec) so we can get those issues prioritized in the CSSWG? I'd be happy to focus on the issues that allow us to get this landed.

[annevk]

@fantasai raised a number of issues on the CSS side and I believe she intends to raise more. And we need the CSS side to be stable (which FPWD does not indicate at all; the CSS WG is quite notorious for renaming things late in the game) to be able to fully test this feature end-to-end, which is a pre-requisite for our criteria: https://whatwg.org/working-mode#changes. (@fantasai did indicate above that she hoped that it didn't matter whether the CSS side was stable or not, but it does matter to our process.)

[rachelandrew]

@fantasai if you have more issues in mind, could you raise them? I can get them on the agenda and work through them once we know what they are.

[dizhang168]

We should move the conversation about CSS+HTML integration to https://github.com/w3c/csswg-drafts/issues/11328 and keep this PR about HTML spec changes only.

[mfreed7]

Two comments here:

1. It seems like the reading-flow spec has been "stable" for some time now. Perhaps we could re-evaluate this spec PR and get it landed?

2. One issue has been raised by a developer (see https://crbug.com/436071736) based on the shipped implementation in Chrome. See this repro:

<dialog> <button>B</button> <button>A</button> </dialog>
<style> dialog:open { display: flex; flex-direction: row-reverse; reading-flow: flex-visual; } </style>
<script> document.querySelector('dialog').showModal(); </script>

The dialog is opened with <button>B</button> focused, because that's the first one in the DOM tree. That's correct according to the current spec:

1. The dialog focusing steps step 4 says to set control to the focus delegate of subject.
2. The focus delegate algorithm step 6 looks at the children of the dialog in tree order. I.e. in the repro for this bug, the "B" button.
3. Step 6.2 of the focus delegate algorithm says that if focusTarget is a dialog element and descendant is sequentially focusable, then set focusableArea to descendant. So "B" gets focused.

But it seems like if reading-flow is being used, perhaps this algorithm should change to focus the first thing that would be focused by the "normal" sequential focus algorithm, as defined in this spec PR? For the above repro, that'd be "A".