Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Treegrid example: Update to use APG Example template for documentation #710

Merged
merged 11 commits into from
Jun 18, 2018
Merged

Treegrid example: Update to use APG Example template for documentation #710

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b0a3204
added documentation to treegrid example
jongund Jun 8, 2018
755cba9
added documentation to treegrid example
jongund Jun 8, 2018
375614d
fixed template and spelling errors
jongund Jun 11, 2018
91350a0
fixed template and spelling errors
jongund Jun 11, 2018
f1ba3cd
added back in deleted content
jongund Jun 13, 2018
adfcca7
added back in deleted content
jongund Jun 13, 2018
67fd8d9
updated based on Matt Kings suggestions
jongund Jun 13, 2018
8577d84
updated document based on MK feedback
jongund Jun 14, 2018
0b8a381
fixed some bugs
jongund Jun 15, 2018
fa6e841
fixed some bugs
jongund Jun 15, 2018
044f2dd
removed the use of aria-hidden attribute in example
jongund Jun 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion examples/treegrid/css/expand-icon-highlighted.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 18 additions & 6 deletions examples/treegrid/css/treegrid-1.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
}

#treegrid tr {
display: table-row;
cursor: default;
}

#treegrid tbody td {
cursor: default;
}

Expand All @@ -30,14 +35,20 @@
padding-left: 3ch;
}

#treegrid :focus {
background-color: hsl(230, 60%, 40%);
color: white;
outline: 0;
#treegrid a {
padding-left: .25ch;
padding-right: .25ch;
}

#treegrid :focus a {
color: white;
#treegrid tr:focus,
#treegrid td:focus,
#treegrid a:focus {
outline: 2px solid hsl(216, 94%, 70%);
background-color: hsl(216, 80%, 97%);
}

#treegrid a:focus {
border-bottom: none;
}

/* Hide collapsed rows */
Expand All @@ -59,6 +70,7 @@
padding-left: 10ch;
}


/* Collapse/expand icons */
#treegrid tr > td:first-child::before {
font-family: monospace;
Expand Down
2 changes: 1 addition & 1 deletion examples/treegrid/js/treegrid-1.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ function TreeGrid (treegridElem, doAllowRowFocus, doStartRowFocus) {
}
}

function getAriaExpandedElem(row) {
function getAriaExpandedElem (row) {
return doAllowRowFocus ? row : getNavigableCols(row)[0];
}

Expand Down
223 changes: 194 additions & 29 deletions examples/treegrid/treegrid-1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,6 @@
<head>
<meta charset="utf-8" />

<!--
Give this example implementation a name and put it in the title element,
e.g., "Checkbox" if implementing the checkbox pattern.
The name should be unique if the pattern will have multiple implementations,
e.g., "Simple Two-State Checkbox" or "Three-State Checkbox".
-->
<title>Treegrid Email Inbox Example | WAI-ARIA Authoring Practices 1.1</title>

<!-- Core js and css shared by all examples; do not modify when using this template. -->
Expand Down Expand Up @@ -72,8 +66,17 @@
</script>
</head>
<body>
<nav aria-label="Related Links" class="feedback">
<ul>
<li><a href="../../#browser_and_AT_support">Browser and Assistive Technology Support</a></li>
<li><a href="https://github.com/w3c/aria-practices/issues/new">Report Issue</a></li>
<li><a href="project_url">Related Issues</a></li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The project_url is https://github.com/w3c/aria-practices/projects/17

<li><a href="../../#treegrid">Treegrid Design Pattern</a></li>
</ul>
</nav>
<main>
<h1>Treegrid Email Inbox Example</h1>

<p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to keep this paragraph

<strong>NOTE:</strong> This example page is not yet complete.
Development of this example is tracked by
Expand Down Expand Up @@ -166,15 +169,20 @@ <h2 id="ex_label">Example</h2>
</div>

<div role="separator" id="ex_end_sep" aria-labelledby="ex_end_sep ex_label" aria-label="End of"></div>
<h4>Notes</h4>
<p>In general, this type of treegrid acts mostly as a tree with cells. The interactions
are the same as a tree, until one begins navigating by cells (via tab to an interactive cell or
right arrow on an expanded row).</p>

</section>

<section>
<h2>Accessibility Features</h2>

<p>Focusable Elements in Current Row</p>
<ul>
<li>This example uses the roving tabindex technique to manage the tabbing into and our of the treegrid and tabindex values are managed through javascript.</li>
<li>If a <code>gridcell</code> contains a focusable element (e.g. <code>a</code>, <code>input</code>), the focusable element gets focus instead of the <code>gridcell</code>. In this example the e-mail address column contains links, so the link receives focus when the user navigates to the <code>gridcell</code>.</li>
<li>The e-mail address link in the current message row with focus is included in the tabbing order (e.g. <code>tabIndex=<q>0</q></code>) of the page, all other links in the <code>treegrid</code> are not in the tabbing order of the page (e.g. <code>tabIndex=<q>-1</q></code>).</li>
<li>
</ul>

<p>Markup used:</p>
<ul>
<li>roles used are treegrid, row, gridcell and columnheader.</li>
Expand All @@ -195,15 +203,12 @@ <h2>Accessibility Features</h2>
<li>aria-labelledby or aria-describedby for headers? Not currently used, awaiting discussion. Some UA + screen reader combinations seem to be determining this automatically via the table structure.</li>
<li>aria-readonly: in ARIA 1.0, a grid/treegrid is editable by default. However, there is no default in ARIA 1.1. Firefox currently implements the ARIA 1.0 concept for this, which means that "editable" is read for every cell unless aria-readonly="true" is used on the treegrid. <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1359482">A bug has been filed in Mozilla to not propagate the readonly/editable state to descendant gridcells unless it is specified via aria-readonly</a>.</li>
</ul>

</section>

<section>
<h2 id="kbd_label">Keyboard Support</h2>

<p>Note (TBD): the behavior for <kbd>Left arrow</kbd> and <kbd>Right arrow</kbd> should be switched for right-to-left language content!!</p>

<table aria-labelledby="kbd_label" class="def">
<table aria-labelledby="kbd_label" class="def">
<thead>
<tr>
<th>Key</th>
Expand Down Expand Up @@ -370,30 +375,190 @@ <h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
</thead>
<tbody>
<tr>
<th scope="row"><code>RoleName</code></th>
<th scope="row"><code>treegrid</code></th>
<td><!-- Leave this cell blank in rows where a role is being described. --></td>
<td><code>HTML_ELEMENT</code></td>
<td><code>table</code></td>
<td>
Describe usage/purpose, e.g., indicates the focusable element that serves as the ...
Identifies the element as a <code>treegrid</code>.
</td>
</tr>
<tr>
<td>
<!-- Leave this cell blank in rows that describe attributes applied to the element with the previously described role.
Make a row like this for each attribute/value pair.
-->
</td>
<th scope="row"><code>AttributeName=<q>AttributeValue</q></code></th>
<td><code>HTML_ELEMENT</code></td>
<th scope="row"><code>aria-label=<q>ARIA Treegrid Example</q></code></th>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can remove the actual literal string and replace with STRING. This is what we do on other example pages so that if we change the label we do not have to also change the documentation.

EX: <th scope="row"><code>aria-label=<q>STRING</q></code></th>

Otherwise, update to use the new label value.

<td><code>table</code></td>
<td>
<ul>
<li>explanation of usage, purpose, benefit, and/or guidance relevant to this implementation.</li>
<li>If making multiple statements, use list for brevity and clarity</li>
<li>Do not make a single item list.</li>
<li>Provides an accessible name for the <code>treegrid</code>.</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change to:
Provides an accessible name, which is required for <code>treegrid</code> elements.

Then there is no need for the <ul> in this cell.

<li><code>treegrid</code> requires an accessible name.</li>
</ul>
</td>
</tr>
</tbody>
<tr>
<th scope="row"><code>columnheader</code></th>
<td><!-- Leave this cell blank in rows where a role is being described. --></td>
<td><code>th</code></td>
<td>
<ul>
<li>Identifies the element as a <code>columnheader</code>.</li>
<li>Column headers provide context (e.g. label) for the values of the <code>gridcell</code>s in the <code>treegrid</code>.</li>
</ul>
</td>
</tr>
<tr>
<th scope="row"><code>row</code></th>
<td><!-- Leave this cell blank in rows where a role is being described. --></td>
<td><code>tr</code></td>
<td>
<ul>
<li>Identifies the element as a <code>row</code> in the <code>treegrid</code>.</li>
<li>The accessible name for the <code>row</code> comes from concatenating the text content of the child <code>gridcell</code>s.</li>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>tabindex=<q>-1</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li>Makes the <code>row</code> element focusable without including it in the tab sequence of the page.</li>
<li>All <code>row</code> and <code>gridcell</code> elements are focusable, but only one is included in the tab sequence.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>tabindex=<q>0</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li>Includes the <code>row</code> element in the tab sequence.</li>
<li>Only one <code>row</code> or <code>gridcell</code> in the <code>treegrid</code> has <code>tabindex=&quot;0&quot;</code>.</li>
<li>In this implementation, the first <code>row</code> in the <code>treegrid</code> is included in the tab sequence when the page loads.</li>
<li>
When the user moves focus in the <code>treegrid</code>, the element included in the tab sequence changes to the element with focus as described in the section on
<a href="../../../#kbd_roving_tabindex">roving tabindex.</a>
</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-expanded=<q>false</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li>Indicates the <code>row</code> can show or hide other message rows within this <code>treegrid</code>.</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change to:

Indicates the <code>row</code> can be expanded to show rows for replies to the message.

Then you can delete the second bullet and eliminate the <ul>

<li><code>aria-expanded=<q>false</q></code> indicates the message rows that responded to this e-mail are hidden.</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-expanded=<q>true</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li>Indicates the <code>row</code> can show or hide other message rows within this <code>treegrid</code>.</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change to:

Indicates the <code>row</code> can be collapsed to hide subsequent child rows containing information about replies to the message.

Then delete the second bullet and the <ul>.

<li><code>aria-expanded=<q>true</q></code> indicates the message rows that responded to this e-mail are visible.</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-hidden=<q>false</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li><code>aria-hidden</code> is used to control the information available to assistive technologies.</li>
<li>When the <code>row</code> is visible (e.g. a top level message or a message whose parent message is expanded), <code>aria-hidden=<q>false</q></code> makes the message row information available to assistive technologies.</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-hidden=<q>true</q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li><code>aria-hidden</code> is used to control the information available to assistive technologies.</li>
<li>When a message <code>row</code> is <strong>not</strong> visible (e.g. is parent message is collapsed), <code>aria-hidden=<q>true</q></code> <strong>hides</strong> the message row information from assistive technologies.</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-level=<q><em>number</em></q></code></th>
<td><code>tr</code></td>
<td>
<ul>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For simplicity and clarity, I recommend replacing the bullets in this list with the following to be consistent with the wording we use in the tree examples:

  • Defines the level of the row in the hierarchical treegrid structure.
  • Counting is one-based.
  • Root rows have aria-level=“1”.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made the change

<li>Defines the level of the row in the hierarchical treegrid structure.</li>
<li>Counting is one-based.</li>
<li>Root rows have aria-level=“1”.</li>
</ul>
</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-setsize=<q><em>number</em></q></code></th>
<td><code>tr</code></td>
<td>
Identifies the number of message rows that responded to the parent e-mail message.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommend the following wording to be consistent with the tree examples:

Defines the number of rows in the set of rows that are in the same branch and at the same level within the hierarchy.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made the change

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm... still looks the same to me.

</td>
</tr>
<tr>
<td>
</td>
<th scope="row"><code>aria-posinset=<q><em>number</em></q></code></th>
<td><code>tr</code></td>
<td>
<ul>
<li>Defines the position of the row within the set of other rows that are in the same branch and at the same level within the hierarchy.</li>
<li>Counting is one-based, not zero-based.</li>
</ul>
</td>
</tr>
<tr>
<th scope="row"><code>gridcell</code></th>
<td><!-- Leave this cell blank in rows where a role is being described. --></td>
<td><code>td</code></td>
<td>
Identifies the element as a <code>gridcell</code>.
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>tabindex=<q>-1</q></code></th>
<td><code>td</code></td>
<td>
<ul>
<li>Makes the <code>gridcell</code> element focusable without including it in the tab sequence of the page.</li>
<li>All <code>row</code> and <code>gridcell</code> elements are focusable, but only one is included in the tab sequence.</li>
</ul>
</td>
</tr>
<tr>
<td></td>
<th scope="row"><code>tabindex=<q>0</q></code></th>
<td><code>td</code></td>
<td>
<ul>
<li>Includes the <code>gridcell</code> element in the tab sequence.</li>
<li>Only one <code>row</code> or <code>gridcell</code> in the <code>treegrid</code> has <code>tabindex=&quot;0&quot;</code>.</li>
<li>In this implementation, the first <code>row</code> in the <code>treegrid</code> is included in the tab sequence when the page loads.</li>
<li>
When the user moves focus in the <code>treegrid</code>, the element included in the tab sequence changes to the element with focus as described in the section on
<a href="../../../#kbd_roving_tabindex">roving tabindex.</a>
</li>
</ul>
</td>
</tr> </tbody>
</table>
</section>

Expand All @@ -403,11 +568,11 @@ <h2>Javascript and CSS Source Code</h2>
<ul>
<li>
CSS:
<a href="css/treegrid-1.css" type="tex/css">example_name.css</a>
<a href="css/treegrid-1.css" type="text/css">treegrid-1.css</a>
</li>
<li>
Javascript:
<a href="js/treegrid-1.js" type="text/javascript">example_name.js</a>
<a href="js/treegrid-1.js" type="text/javascript">treegrid-1.js</a>
</li>
</ul>
</section>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a link at the end of the file back to the pattern than needs to be updated. Github doesn't let me comment on that line.

Expand All @@ -430,7 +595,7 @@ <h2 id="sc1_label">HTML Source Code</h2>
</main>
<nav>
<!-- Update the pattern_ID parameter of this link to refer to the APG design pattern section related to this example. -->
<a href="../../#pattern_ID">EXAMPLE_NAME Design Pattern in WAI-ARIA Authoring Practices 1.1</a>
<a href="../../#treegrid">Treegrid Design Pattern in WAI-ARIA Authoring Practices 1.1</a>
</nav>
</body>
</html>