Hyperlinks, scrollbars or pagination inside role=document

[brennanyoung]

I'm continually amused and exasperated by the caveats that surround the use of the application and document roles, both in the official spec and in any other discussion of them.

I believe that I understand how they should be used, but almost every time they are discussed, fingers start wagging and warnings are issued before or instead of any actual guidance or example being provided. This is not helpful.

Assume we have a Rich Internet Application with buttons, meters, menus and live regions. Almost everything is either presentational or operable. With one exception.

Inside this application is a "document", consisting of headings, lists, data tables and groups of term-definition pairs. It's for browsing.

Please correct me if I have not presented a very appropriate use case for application/document in the above 'sketch'. It happens to be the actual arrangement in the digital product I work on.

Now, lets assume that the nested document has a scrollbar or pagination controls - to help browsing. How might that work? Let's further suggest that the document also contains hyperlinks, which are also far from rare in non-operable rich text views. How might those hyperlinks work? What model of keyboard operation should I expect or work towards?

It will come as no surprise that ATs which offer a "browse mode" (aka "document mode" or "reading mode") struggle to deal gracefully with hyperlinks inside document role content. In NVDA, the tab sequence somehow seems to get 'trapped' inside the nested document if a hyperlink within it gets focus. I don't yet know whose fault this is, and the spec does not offer any guidance to help me understand what should/might be happening, or produce a proper bug report.

Are there any guidelines beyond "don't do this, but if you must do it, be careful"? (The implicit message is "you're on your own"). Why not? Can't we make some?

Rather than wagging fingers and scary warnings from the high priesthood, I would welcome a proper example in ARIA practices which explores some of the nuances of these poorly understood and underdocumented roles, and which might help AT vendors arrive at some robust and predictable implementations.

[JAWS-test]

I don't really understand the question because role=document just establishes the default mode of the page. I.e. a page without role=application is automatically in the mode created with role=document inside role=application. Thus all elements (like Hyperlinks, scrollbars or pagination) can be operated within role=document like on an ordinary web page. If this is not possible with NVDA, then this is a bug of the screen reader.

[brennanyoung]

That's what I was arriving at too. I also think it's an NVDA bug, but the guidelines don't make it at all clear whether I am doing something wrong, or whether NVDA is failing. The spec says nothing about tab stops in nested documents.

The actual issue is not that hyperlinks or pagination buttons in the nested document don't work, but that once you focus them, you can't "exit" the document (i.e. return to the outer application) by tabbing, and in some cases, the browse shortcuts break because NVDA went into forms mode. (You can actively switch back to document mode, of course).

This might be regarded as a violation of SC 2.1.1 Keyboard or SC 2.1.2 No Keyboard Trap.

Isn't the problem more that a nested document is (itself) a tab stop (easy to overlook but mentioned in the spec as "user agent focus"), and if you have tab-focusable things such as hyperlinks inside something which is a tab stop, there's trouble. How could the spec make this situation clearer? Should it be forbidden? How might it work otherwise?

How does JAWS handle this case?

If hyperlinks in nested documents have particular constraints, or if there is room for doubt about how ATs should behave in these cases, then this should be documented, and (preferably) some recommendations will be made via an Authoring Guideline example.

[scottaohara]

some initial thoughts:

1. this generally seems like an issue for APG, particularly per the request of nuanced author guidance.
2. issues with tabbing in/out of a nested document would be better discussed by reviewing a reduced test case. These are likely either issues with the author implementation, and / or of the browser/AT. I don't think there's a reason the spec should have to explicitly state how tabbing to elements within a document should behave, as that would be re-specifying implicit behavior expected of a web page.
3. what about the application and document definitions are unclear in regards to how they should be used by authors or implemented by UAs? Per point 1, detailed author guidance should be over in APG... but in lieu of waiting for that to be written and published, are there clarifications and smaller examples that could help demonstrate use in the spec? I'm particularly looking at application as being potentially in need of any such clarifications... maybe further emphasizing points like "When there is a need to create an element with an interaction model that is not supported by any of the WAI-ARIA widget roles, authors MAY give that element role application." where even though this role is named application, it doesn't necessarily mean "your entire web application needs to be contained within this role".... which might then negate some author's need to nest a document within an application, if their UI is more precisely marked up to only use the application role for the specific UI elements that actually require a screen reader to not be in browse mode?

[JAWS-test]

How does JAWS handle this case?

I am not aware of any problems with JAWS in connection with role=document and nested interactive elements. However, to investigate your problem in more detail, it is necessary that you share source code (anonymized if you like)

[JAWS-test]

Interactive elements within elements that receive focus should not cause problems, are not prohibited, and should not cause keyboard trapping. If this occurs, NVDA should fix the problem

[brennanyoung]

what about the application and document definitions are unclear in regards to how they should be used by authors or implemented by UAs?

Re: the spec for document

Current Text:

Because assistive technologies that have a reading mode default to that mode for all elements except for those with either a widget or application role, the only circumstance where the document role is useful for changing assistive technology behavior is when the element with role document is a focusable child element of a widget or application.

Yikes. The "Because... behavior is when" explanatory preamble contains a tangle of qualifiers and detours, so that any suggestion that this might be normative is lost. (Can we treat the words "the only circumstance where..." as a proxy for 'normative'?) In the existing copy, it seems that the use case for document is much more about changing AT behavior, rather than reflecting the Info and Relationships expressed in the presentation. Is that really how we want to think about it?

Here is my suggestion for some replacement copy for the above cited paragraph which I think/hope provides clearer guidance for authors, UA/AT vendors and automated test engineers about document:

An element with document role MUST be a descendent of an element with an application or widget role and MUST be a user-focusable element. This is because assistive technologies that have a reading mode default to that mode for all elements except for those with either a widget or application role. A document nested within an application or widget MAY contain focusable child elements, but authors should be aware that these will introduce complexity to the overall focus sequence.

Would it not be helpful to have a "Used in Roles" row in the table of characteristics, with "application" and widget roles listed?

Re: the spec for application

article is mentioned as an alternative means to embed static text inside an application, although there is no guidance for choosing this over 'document'. Is there any difference? (The spec for article does not mention the application context.) What does article give you that you don't get with document? Can you put an article inside other kinds of widget?

Citing @scottaohara above

even though this role is named application, it doesn't necessarily mean "your entire web application needs to be contained within this role".... which might then negate some author's need to nest a document within an application, if their UI is more precisely marked up to only use the application role for the specific UI elements that actually require a screen reader to not be in browse mode?

Thank you!!! Yes it might indeed. And it might not. It really sounds like that need is not entirely legitimate. I think lack of clarification of this very point is the key shortcoming for the spec on application.

In our (very concrete) case, there is literally nothing except the nested document that we want to be handled in browse mode. It's a true RIA, rather like a video game, dominated by a main canvas view, with 'NPCs' that talk, and a constantly-updating HUD. The main operable UI consists of a very exotic pseudo-menu that contains spinbuttons and sliders.

Quite naturally, I would expect that putting the whole thing inside a single application is appropriate, despite the caveats, but how can I know? When I look for guidance, I find only vague warnings, or suggestions that privilege the idiom of documents-and-forms. This thread is the only place I have found any enlightenment. (It's really helpful btw!)

I hope that it will be understood why breaking the thing into separate but wholly contiguous "applications" (which are collectively the same RIA) seems conceptually wrong.

If we have any hopes that ARIA might one day become part of a universal accessible gaming experience, it seems obvious that we should be able to find more explicit and detailed guidance about this kind of content than is available today.

After this discussion I now begin to conceive the application role as something which is not anything as high-level as an RIA. It is 'just' a widget that has no established idiom. If this is true, then I suggest that the name is poorly chosen.

The conceptual step from complex, non-document-centric RIA with an exotic UI to an overarching role="application" is not a huge irrational leap. They even have nomenclature in common. And so does ARIA itself. Others will make that leap too. Some clearer guidance here will really help us land on both feet.

[JAWS-test]

@brennanyoung

A document nested within an application or widget MAY contain focusable child elements, but authors should be aware that these will introduce complexity to the overall focus sequence.

I don't understand. If a page has role=application and contains multiple areas with role=document, then all interactive elements get focus in order, as if the page did not have the two roles. The areas with role=document only add some navigation steps on these areas. What is complex about that?

[JAWS-test]

@scottaohara: I wonder if article only works like document because it is a child element of document in the hierarchy of ARIA roles. If so, then the ARIA role comment should also inherit this property from article?

[brennanyoung]

@JAWS-test Whatever it was that was happening before with NVDA is no longer reproducible since I updated. I assume someone else caught and fixed the issue?

Now the nested tab stops are simply inserted into the sequence (in source order) and it is possible to 'escape' the document both with tabbing, and with the 'virtual cursor' after activating any of them.

Still I would like to see it explicitly mentioned that the nested document may contain tab stops, because the current wording implies that only static text is permitted there.

[JAWS-test]

@brennanyoung

Still I would like to see it explicitly mentioned that the nested document may contain tab stops, because the current wording implies that only static text is permitted there.

Where does it say that? I don't read that in the specification. But if it is formulated in a misleading way, then of course it should be clarified. My understanding is that role=application can contain role=document. The role=document can in turn contain all widgets and role=applications, which in turn contain role=document, so any nesting should be possible (although in practice probably not useful most of the time).

[brennanyoung]

Where does it say that? I don't read that in the specification.

It doesn't say it, but it implies it.

The use case suggested is browsing static text, and this guidance is spread over the two specs for application and document, both of which emphasise 'reading mode'. That's a very ambiguous way of specifying that operable content is permitted in amongst the static text. Especially because tab stops within tab stops are typically discouraged, or even regarded as an error. I am seeking clarity, so that authors are in no doubt.