CodeSnippet: the scrollable content needs to be WCAG 1.4.10 compliant

guigueb commented 3 years ago

CodeSnippet needs to deal with scrolling its data. This issue should wait until #7579 and #8056 are complete as the circumstances around scrolling will become more apparent and predictable.

For reference... https://www.w3.org/WAI/WCAG21/Understanding/reflow.html

Summary

In order for the CodeSnippet to be WCAG 1.4.10 compliant the component will need to know more information about what the data it is displaying.

About data for a horizontal language....

typically the data will be wrapped and there will be a vertical scrollbar only
wrapText will need to be smarter (where some whitespace is non-breaking and some non-whitespace is breaking)
if the user sets wrapped=false... -- we need to assume the data will overflow the horizontal axis and show the horizontal only -- we need to assume the number of rows will show without needing a vertical scrollbar -- we need to know if the language is RTL or LTR and justify and initially display the data accordingly

About data for a vertical language....

typically the data will be wrapped and there will be a horizontal scrollbar only
wrapText will need to be smarter (where some whitespace is non-breaking and some non-whitespace is breaking)
if the user sets wrapped=false... -- we need to assume the data will overflow the vertical axis and show the vertical only -- we need to assume the number of rows will show without needing a horizontal scrollbar

Justification

CodeSnippet to be WCAG 1.4.10 compliant

Desired UX and success metrics

Testcase - horizontal language with wrapText=on (the default): The client supplies data for a horizontal language. Long lines will be wrapped. A vertical scrollbar will show when data exceeds the visible (closed or expanded) area vertically. A horizontal scrollbar will never show.

Testcase - horizontal language with wrapText=off: The client supplies data for a horizontal language. Long lines will NOT be wrapped. A horizontal scrollbar will show when data exceeds the visible (closed or expanded) area horizontally. A vertical scrollbar will never show.

Testcase - horizontal language with LTR BiDi: The client supplies data for a horizontal LTR language. The data shows left justified. The scrollbar behavior is described in other stories.

Testcase - horizontal language with RTL BiDi: The client supplies data for a horizontal RTL language. The data shows right justified. The scrollbar behavior is described in other stories.

Testcase - vertical language with wrapText=on: The client supplies data for a vertical language. Long lines will be wrapped. A horizontal scrollbar will show when data exceeds the visible (closed or expanded) area horizontally. A vertical scrollbar will never show.

Testcase - vertical language with wrapText=off: The client supplies data for a vertical language. Long lines will NOT be wrapped. A vertical scrollbar will show when data exceeds the visible (closed or expanded) area vertically. A horizontal scrollbar will never show.

Testcase - vertical language with LTR/RTL BiDi: I'm not sure if there is a similar concept of LTR/RTL for vertical languages. TTB/BTT (top to bottom / bottom to top)

"Must have" functionality

Pretty much need it all

Specific timeline issues / requests

Without the CodeSnippet controller being scrollable IBM Cognos can not use CodeSnippet. Because the content in closed or expanded mode will not be visible unless you copy it somewhere else.

Available extra resources

What resources do you have to assist this effort?

Maybe.

guigueb commented 3 years ago

Some questions/answers from our global team...

Q) are there specific terms to use when talking about horizontal vs vertical languages? A) Yes - horizontal/vertical text layout

Q) is there a concept of LTR/RTL for vertical languages (TTB/BTT: top to bottom/bottom to top)? A) horizontal text layout (LTR): is top to bottom and left to right horizontal text layout (RTL): is top to bottom and right to left vertical text layout: is always top to bottom and right to left

Q) horizontal languages can be wrapped (using a basic concept of breaking on whitespace), does this apply to vertical languages? A) Not specifically white space wrapped - see comment below.

Q) ideally horizontal languages should be broken in a smart way (where some whitespace is non-breaking and some non-whitespace is breaking)… is there a similar concept for vertical languages? A) both horizontal/vertical text layout should break in a smart way - suggestion: ICU/Java BreakIterator.

The full answer for the last question is... No matter if the text is displayed horizontally or vertically, line wrapping should use rules based on written script/character properties in general. Unicode database maintain such properties. See UAX-14 - https://www.unicode.org/reports/tr14/ for the details. In general, you should use proper line breaking detection code like ICU/Java BreakIterator.

sstrubberg commented 1 year ago

@mbgower Can you chime in on this one? Would love to know your perspective on whether or not we're meeting the WCAG spec and what action we can take from this. Thanks!

tay1orjones commented 1 year ago

Some content is exempt from the requirement:

Content which requires two-dimensional layout for usage or meaning cannot reflow without losing meaning, and is therefore out of scope of this Success Criterion.

I think you could argue that code content requires two-dimensional layout for usage and meaning. Reflow within a CodeSnippet is not ideal and hurts overall comprehension of the content. Code formatting (indentation, line length, etc.) is intentional and crucial to understanding.

For the BiDi concerns, we've added a series of helper components to facilitate rendering these properly. Docs are here - I don't think we've tested them within a CodeSnippet yet though.

tay1orjones commented 1 year ago

In general, you should use proper line breaking detection code like ICU/Java BreakIterator.

This is ultimately up to how you format content being placed into CodeSnippet. We're probably not going to provide a code formatter within the component to handle all this - it will be up to your application to provide formatted content to avoid reflow in a direction you deem unacceptable.

For instance, if we wanted to avoid horizontal scrollbars on CodeSnippets on the Carbon website, we'd probably use prettier configured with a super-short line length to ensure the code is formatted properly when the content is being written, rather than consider baking in formatting to CodeSnippet itself.

mbgower commented 1 year ago

@mbgower Can you chime in on this one? Would love to know your perspective on whether or not we're meeting the WCAG spec and what action we can take from this. Thanks!

Yep, I think one could make a case that code snippets are using a horizontal width for a reason. There may be cases where line reflow can be accommodated, and then you could do what @guigueb is suggesting. But I think as a starting point, if your code snippet does not have a capacity to do elegant word wrapping and you are trying to demonstrate it on lines, code width is defendable as an exception. (There's a reason one has to turn on autowrapping in various tools, instead of it being like that by default).

I would not prioritize fixing this. It's not defying the overall goal of Reflow, which is to ensure when there is no reason to preserve line breaks, the text can reflow. (Think of poetry as another example of this kind of thing.)

A horizontal scrollbar will show when data exceeds the visible (closed or expanded) area horizontally. A vertical scrollbar will never show.

@guigueb BTW, I have seen code snippets where the vertical space is constrained and vertical scrolling is needed; I don't see a problem with that

guigueb commented 1 year ago

I am currently on vacation until February. When I get back I will review and comment on this (code snippet).

Our product uses code snippet in several places and we have received a number of comments/concerns of its useability. Most of the accessibility issues have been covered by the workaround... "copy/paste the contents into a tool of your liking". I'm looking forward to seeing what you come up with.

Bill

On Tue, Jan 10, 2023, 21:55 Scott Strubberg, @.***> wrote:

@mbgower https://github.com/mbgower Can you chime in on this one? Would love to know your perspective on whether or not we're meeting the WCAG spec and what action we can take from this. Thanks!

— Reply to this email directly, view it on GitHub https://github.com/carbon-design-system/carbon/issues/8057#issuecomment-1377773695, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABNSNCWSNH2H75N2M7BKGTTWRW5DLANCNFSM4Y6ATL7A . You are receiving this because you authored the thread.Message ID: @.***>

carbon-design-system / carbon