Develop example of a tri-state toggle button

[mcking65]

The ARIA 1.1 specification refers readers to ARIA Practices for examples of toggle buttons that have aria-pressed="mixed".

Add an example of a tri-state toggle button to the button examples page
and add appropriate guidance to the button design pattern.

[kleinfreund]

Hey, I’d like to work on this. I have a few questions.

The examples on Button Examples are not organized well. I would like to separate the example JS/CSS into their own directories (i.e. button/, toggle-button-twostate/ and toggle-button-tristate/. If this is something you want, should it be done in a separate pull request? If so, I would prefer to do that first, because it would allow me to write some generic button styles that the specific examples can reuse.

Also, I wonder what the correct spelling of tristate/tri-state is. The spec language uses tristate when they refer to the value type (reference). However, in natural language, I believe it should be tri-state (and two-state respectively).

I’m also having a hard time figuring out what a good example might be for a tri-state toggle button. My concept looks like this:

---

A sound control with the following elements:

• A main button, labelled "Sound"
• Two additional buttons "Audio" and "Vibration"

The main button is the one that can exist in three states ("true", "false" and "mixed"). Toggling it cycles through the two usual states of a toggle button, "true" and "false". Whenever the main button is toggled, the dependant buttons receive the same state (e.g. turning off "Sound" also turns off "Audio" and "Vibration").

The dependant buttons are able to bring the main button in the "mixed" state. This happens whenever the dependant buttons don’t share the same state. Otherwise, the main button will receive the shared state of the dependant buttons.

---

What do you think? Originally, I thought I could implement the tri-state buttons that are commonly used for phones’ audio control: Tapping the button cycles through the modes "Sound", "Vibration" and "Silent". However, the specification doesn’t allow a toggle button to trigger the "mixed" state on itself (reference).

[mcking65]

@kleinfreund commented:

Hey, I’d like to work on this. I have a few questions.

Excellent! Thank you! And, thank you for raising your questions and proposal specifics here before working on a PR.

BTW, sorry for the long delay with the answers. We were burning the midnight oil for the last several weeks to get the first release out, which is happening today! This example is currently in the plan for the release next Spring.

The examples on Button Examples are not organized well. I would like to separate the example JS/CSS into their own directories (i.e. button/, toggle-button-twostate/ and toggle-button-tristate/. If this is something you want, should it be done in a separate pull request? If so, I would prefer to do that first, because it would allow me to write some generic button styles that the specific examples can reuse.

It would be fine to create separate css and js files, but we have been leaning toward a flatter directory structure. For example, look at the structure of the grid example directory. That would mean, for instance, having:

• examples/button/js/button.js
• examples/button/js/toggle-button-twostate.js
• examples/button/js/toggle-button-tristate/.js

To keep the supporting documentation on the example page simpler, we have been preferring one example per page.
I think the toggle buttons should have their own html page.
However, the use of states and properties is so similar for two-state and tri-state toggles, they could share the same page.
So, we could have a button.html and a toggle-button.html.

I am OK with a single PR or doing it in stages. It is easier to review small changes. But, if you are waiting around on a review and merge to continue, that could slow you down, especially over the next few weeks with the holidays and other end of year/start of year work that will delay reviews.

Also, I wonder what the correct spelling of tristate/tri-state is. The spec language uses tristate when they refer to the value type (reference). However, in natural language, I believe it should be tri-state (and two-state respectively).

Agree.

I’m also having a hard time figuring out what a good example might be for a tri-state toggle button. My concept looks like this:

---

A sound control with the following elements:

• A main button, labelled "Sound"
• Two additional buttons "Audio" and "Vibration"

The main button is the one that can exists in three states ("true", "false" and "mixed"). Toggling it cycles through the two usual states of a toggle button, "true" and "false". Whenever the main button is toggled, the dependant buttons receive the same state (e.g. turning off "Sound" also turns of "Audio" and "Vibration").

The dependant buttons are able to bring the main button in the "mixed" state. This happens whenever the dependant buttons don’t share the same state. Otherwise, the main button will receive the shared state of the dependant buttons.

---

What do you think? Originally, I thought I could implement the tri-state buttons that are commonly used for phones’ audio control: Tapping the button cycles through the modes "Sound", "Vibration" and "Silent". However, the specification doesn’t allow a toggle button to trigger the "mixed" state on itself (reference).

Good catch in the spec language there.
However, I am not sure that language is meant to restrict a tri-state toggle from cycling through all three of its states directly.
I can't think of a reason why it could not operate like a tri-state checkbox, which it remembers the most recent mixed state of its dependent elements.
This is worth putting on the ARIA agenda; maybe I will end up cleaning up the spec language.
I raised w3c/aria#684.

Regardless, the design of the example needs to consider how a toggle will be announced by a screen reader.
As with two-state toggles, the button label needs to remain constant.
A tri-state toggle will be announced by screen readers as something like pressed, partially pressed, and not pressed.
So, think about how a user might interpret "Sound button not pressed" or "Sound button partially pressed".

Here's another thought. Perhaps we have a set of buttons:

<button aria-pressed="false">Door Locks</button>
<button aria-pressed="false">Front Door Lock</button>
<button aria-pressed="false">Back Door Lock</button>
<button aria-pressed="false">Side Door Lock</button>

• Is the notion that a door is locked when the door lock button is pressed reasonable?
• Is the notion that some doors are locked and some are not locked seem reasonable when the user hears "Door locks button partially pressed"?

[kleinfreund]

Hello there. Some things happened (e.g. dev machine died) and I wasn’t able to work on this when I wanted to.

Anyway, I will now start with part 1 which is cleaning up the existing material (code, potentially language). That will be a separate pull request without new content but changes to existing content. In part 2, I’ll implement the example for the tri-state toggle button. I’ll get back to this issue with my thoughts on what example to use when the time is right.

I just looked at the existing JavaScript and wondered if there is some kind of style guide that is being used apart from the editor config in the repository.

For example:

function init () {

Space between function name and ()?

[kleinfreund]

I had a look at the button.html file. Some questions/observations.

• Why is there a slash (/) character in the meta tag but not in the link tags? Should it be included/omitted in general?
• type="text/javascript" is sometimes omitted from script tags. Should it be included/omitted in general?
• What’s the purpose of the th elements inside tbody > tr? It looks like it’s being used to remove kbd styles, but why? Do th elements inside tbody need to be wrapped in td elements?
• In the table “Role, Property, State, and Tabindex Attributes”, why is “Role” a separate column? One could also list role="button" unter “Attribute”. Is this done to distinct between implicit roles (e.g. for button elements) and explicit roles (e.g. using the role attribute)? I think, the table would be easier to read and understand if the “Role” and “Attribute” columns were merged. Note that I have not checked whether this creates a conflict on other example pages.

[mcking65]

Philipp, Thank you for taking on this issue. I really appreciate it!!

@kleinfreund commented:

I just looked at the existing JavaScript and wondered if there is some kind of style guide that is being used apart from the editor config in the repository.

Please see the code conformance section of the readme. We use eslint to enforce js formatting.

I had a look at the button.html file. Some questions/observations.

We also have a code style guide in the wiki for the following ...

Why is there a slash (/) character in the meta tag but not in the link tags? Should it be included/omitted in general?

Omit on self-closing tags.

type="text/javascript" is sometimes omitted from script tags. Should it be included/omitted in general?

Omitted.

What’s the purpose of the th elements inside tbody > tr? It looks like it’s being used to remove kbd styles, but why? Do th elements inside tbody need to be wrapped in td elements?

It's there so that the key commands have row headers for screen reader users. It is much easier to read that table with a screen reader with the th elements. I didn't realize they were overriding the kbd styling.

In the table “Role, Property, State, and Tabindex Attributes”, why is “Role” a separate column? One could also list role="button" unter “Attribute”. Is this done to distinct between implicit roles (e.g. for button elements) and explicit roles (e.g. using the role attribute)? I think, the table would be easier to read and understand if the “Role” and “Attribute” columns were merged. Note that I have not checked whether this creates a conflict on other example pages.

All the example pages use a common template. The task force decided on this after trying both ways. The previous format was you describe.

The purpose of the current format is to help make it more clear to which element the states and properties are applied.