AccordionBox

• Source Code and Options
• Number of sims that use this component: 64

General Design Considerations

Here’s when and why we use accordion boxes:

• Default state can be expanded or collapsed depending on how the designer wants to scaffold the user interaction. A closed panel can be used to keep the default opening condition of sim from being visually overwhelming, and suggesting a logical route for exploration, for example in Build an Atom and in GE:B (please spell out simulation name).
• Accordion boxes can also be useful for teachers to ask predictive questions.
• Can contain non-interactive readouts, interactive controls, but not sprites (e.g., draggable toolbox items).

Note this design pattern covers multiple PhET Component Types

• AccordionBox.ts
• ExpandCollapseBar.ts
• ExpandCollpaseButton.ts

Aesthetic Considerations

• If space is a concern, the title can be hidden while the accordion box is expanded. Note that an accessible name for the title is always needed and available for the non-visual experience.
• An expanded accordion box cannot overlap other elements when opened (unlike combo box, for instance).
• Always includes an iconed button (+/-), typically to the left of the title.
• Other sim content does not fill the space when an accordion box is collapsed.
• The accordion box content can be expanded or collapsed by default and a change of state for one accordion does not affect the state of other accordion boxes.

Accessibility Considerations

Accessible Components of an Accordion Box

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

• Accordion Header: Label (usually a heading with a +/- icon signalling expand/collapse behaviour) for a section of content (usually a collapsible box). The accordion header could also be an icon, alone. The accordion header serves as a control that can show or hide a section of content.

• Accordion Panel: Section of content (e.g., the content box) associated with an accordion header

• Typically, has a visual title with an icon that indicates expanded and collapsed state.

  • The title may disappear when box is expanded.
  • Focus highlight would go around title in both the expanded and collapsed states, if title remains visible.
  • If title visually disappears when expanded, the focus highlight would be limited to the open/close icon and the designer would need to consider extra padding to ensure a reasonable clickable area.
  • It is possible that the focus highlight can change size when toggling between expanded/collapsed states in the scenario when the expanded box does not have a title.
• The typical structure is a button nested within the parent titling element, likely a heading.
• Typically, the open/close icon does not need to be represented in the Parallel DOM.
• For accessibility the expanded and collapsed states of the box are communicated through a combination of ARIA attributes, aria-expanded, aria-controls, aria-hidden that have to be managed through javascript.

Gesture Support

ToDO.

Keyboard Support

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

QUESTION: It's not clear to me how users get inside a panel, if the panel has no focusable items.

Management of Role, Property, State, and Tabindex Attributes

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

DRAFT: Sample HTML

<! -- expanded state -->
    <h3>
       <button id="accordion-header-01" aria-expanded="true">Factors</button>
    </h3>
    <div id="accordion-panel-01" role="region" aria-labelledby="accordion-header-01">
       <p>Box content.</p>
       <p>More content or even other HTML controls.</p>
    </div>
<! -- collapsed state -->
  <h3>
     <button id="accordion-header-02" aria-expanded="false">Product</button>
  </h3>
  <div id="accordion-panel-02" role="region" aria-labelledby="accordion-header-02" aria-hidden="true">
     <p>Box content.</p>
     <p>More content or even other HTML controls.</p>
  </div>

Supporting Accessibility Resources

• Adapted from ARIA Practices 3.1 Accordion (Sections With Show/Hide Functionality)

Design Doc Content Template Text

Accordion Box

• Accordion Box Title (header):
• Accessible Name: content for the accordon box title
  • Header contains a title? Yes/No, default Yes - actually, title for header should be required.
  • Title is a heading? Yes/No, defaults to Yes
  • If title is heading, set heading level, defaults to H3
  • Accordion title is visually hidden: Yes/No (defaults to No)
• Accordion Box Content (panel):
  • Parent container accordion box contents: defaults to a div
  • Use same convention as other objects and controls.
  • Default open state: expanded/collapsed (defaults to expanded)

Checkbox

• Source Code and Options
• Number of sims that use this component: 97

General Design Considerations

Here’s the when and why we use a checkbox (traditional looking checkbox user interface component) in simulation design.

• Generally, when a secondary or non-essential option needs to be toggled between on and off states
• To toggle more than one option in a group of options
• Checkboxes are often used to allow users to layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.

Note this design pattern covers multiple PhET Component Types

• Question: Are there any other types of visual checkboxes?

Aesthetic Considerations

• Checkbox appears checked or not checked on simulation load
• Appears with a text-based label, or an icon as the label, or a combination of both text and icon
• Title case is used for text-based labels for checkboxes

Accessibility Considerations

• HTML checkboxes (i.e., input type="checkbox") and possibly all visual PhET sim checkboxes are two-state controls that represent the element's "checkedness" state.
• Traditional looking checkboxes with visual labels are generally best represented in the PDOM as an input of type checkbox with an associated label element.
• When the visual label content is an image or a string of text that does immediately translate into a name that clearly communicates what the checkbox is for, non-visually, consider changing the visual string, adding clarifying help text, or providing a more descriptive name as the label element's content in the PDOM. Keep in mind that ideally, the visual text and the text in the PDOM should be the same to support users who use voiced commands.
• Groups of related checkboxes may benefit from being explicitly grouped using a containing element (e.g., fieldset or div) with the ARIA role="group". Grouping checkboxes is optional.
• Explicitly grouped checkboxes may benefit from a group name provided by either an h3 or a legend.
• Checkboxes that appear visually grouped (e.g., by proximity or with a visual box) for convenience or space-saving may not benefit from explicit group semantics in the PDOM.
• When a group is very important, consider using a heading, e.g., h3 as headings are placed in the heading outline which can be navigated with screen reader software whereas the legend element is not placed in the heading hierarchy.

Note: Known issue that some screen readers (i.e., VoiceOver) repeat the checkbox's label content when the label is associated with the input via the for attribute. We discovered that we do not get repetition of the label content when the label comes before the checkbox. When there is no visible screen label, the aria-label attribute is an option, and it also does not cause any repetition.

Gesture Support

ToDO.

Keyboard Support

Management of Role, Property, State, and Tabindex Attributes

Respecting the first rule of ARIA, "use a native HTML element whenever possible", we use native checkbox elements in the PDOM to represent traditional looking checkbox interactions. An HTML checkbox could represent other "switching" interactions that may not visaully look like a checkbox in the simulation, but examples for those are provided elsewhere. Because we use native HTML for checkbox interactions, some of the guidance provided in ARIA Practices for checkbox widgets is not relevant. I have adapted the content from the ARIA practices section for checkbox.

• No explicit ARIA role of checkbox is needed on an native HTML checkbox (input type="checkbox").
• No tabindex required, native HTML checkboxes are focusable elements.
• An HTML checkbox has an accessible label (i.e., accessible name) provided by one of two of the following ways:
  • Visible text content contained within a label element and assocaited to its input with the for attribute.
  • Content within an aria-label attribute set on the input element with type="checkbox".
• When checked, the checkbox element has the attribute checked present.
• When not checked, the checked attribute is not present.
• When partially checked, it has state aria-checked set to mixed. (tri-state checkboxes only)
• When a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role="group" that has the property aria-labelledby set to the ID of the element containing the label or name for the group.
• When the presentation includes additional descriptive static text (i.e., help text) relevant to a checkbox or group of checkboxes, using aria-describedby is an option to provide automatically read help text. We have, however, that automatic helptext is not needed in our sims. Users seem to prefer on-demand help text.

Simplified HTML Examples for PDOM

Options for Checkbox in the A11y API

When creating the common code component, it would be useful to have options to use either a label element or an aria-label attribute to provide the accessible name for the checkbox.

Checkbox with visual label text

Energy Forms and Changes

Visual checkbox with a text-based label:

State Descriptions

<input id=”energy-symbols” type=”checkbox”> <!-- not checked checkbox-->
<label for=”energy-symbols”>Energy Symbols</label>
<p>Observe energy chunks move and change through system.</p>

Responsive Descriptions

• When checked: Symbols flow with energies.
• When unchecked: Energy symbols hidden.

Checkbox without visual label text (option with aria-label)

Area Model Introduction

Visual checkbox with different label

<input id="counting-numbers" type="checkbox" aria-label="Counting numbers">
<p>Use area grid with or without counting numbers in grid cells.</p>

Unnamed group of checkboxes

Gravity Force Lab

Note: still need to finish this example.

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Constant Size</label>
<p>When changing mass, observe constant or changing size of spheres.</p>

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Force Values</label>
<p>Explore value of forces in newtons.</p>

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Scientific Notation</label>
<p>Listen to newtons in scientific notation.</p>

Supporting Accessibility Resources

• Using ARIA, working draft
• HTML5.1, Section 4.10.5.1.15. Checkbox state
• ARIA Practices 1.1 Section 3.6 Checkbox

Checkbox Snippet for Design Document

{{checkbox name}}, checkbox

• Accessible Name:
• Interaction Type: checkbox or non-visual checkbox
• Initial State: checked/ not checked
• (Optional) Help Text:
• (Optional) Context responses or link to section with context responses.
• (Optional) Design Note: Special things about this checkbox, if any.

ComboBox

• Source Code and Options
• Number of sims that use this component: 42

General Design Considerations

• Generally used with limited space and/or a long list of choices
• PhET comboboxes are not auto-select when hovering options with a mouse or when navigating through options with the arrow keys (i.e., different from radio button lists)
• Label for control serves a dual purpose: identifies the combobox (list of options) and identifies the selected option
• Selected item is communicated clearly upon focus and when the list is closed
• Large pointer/click areas: box label and selected item; option labels and images

Aesthetic Considerations

• List can appear above or below the button depending on space considerations
• Can include an indicator image (to the left of the list item)
• The rounded corners of the list should match the rounded corners of the button
• Generally, the list panel is often the same width as the button
• Mouse hover and focus highlights should be considered together

Accessibility

The PhET combobox interaction, visually looks and behaves as a combobox in the sense that a list of hidden options can be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button, which may have a dynamic label (i.e., accessible name) that pops up a listbox with a list of options. Design and interaction details are below.

Gesture Support

ToDO.

Keyboard Support

Role, Property, State, and Tabindex Attributes

(adjusted content from W3C listbox collapsible example, see https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-collapsible.html)

Sample HTML for Combobox

The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA 1.1 Combobox design pattern wasn't and will never be supported. For the accessible representation in the Parallel DOM we implemented this widget as a dynamic button and a popped-up listbox (Bryan Garanventa, 2016). The HTML example is below.

Note: The HTML for this interaction may change when the ARIA role combobox has better support accross assitive technologies.

Molarity Example (10 options)

    <div tabindex="-1" id="container-for-labels">
    <span id="listbox-static-label">Solute</span>
      <button id="listbox-option-dynamic-label" tabindex="0" aria-haspopup="listbox" aria-labelledby="listbox-static-label listbox-option-dynamic-label">Drink Mix</button>
    </div>
    <ul role="listbox" tabindex="0" id="listbox" aria-activedescendant="option-1" aria-labelledby="listbox-static-label" style="list-style:none;">
      <li role="option" id="option-1" class="selected" aria-selected="true">Drink mix</li>
      <li role="option" id="option-2">Cobalt (II) nitrate</li>
      <li role="option" id="option-3">Cobalt Chloride</li>
      <li role="option" id="option-4">Potassium dichromate</li>
      <li role="option" id="option-5">Gold (III) chloride</li>
      <li role="option" id="option-6">Potassium chromate</li>
      <li role="option" id="option-7">Nickel (II) chloride</li>
      <li role="option" id="option-8">Copper sulfate</li>
      <li role="option" id="option-9">Potassium permanganate</li>
      <li role="option" id="option-10">Potassium dichromate</li>
    </ul>
    <!-- help text for combobox -->
    <p>Change a solute and observe differences.</p>

Supporting Accessibility Resources

• Adapted from ARIA Practices Collapsible Listbox Example( 2016)
• The above pattern has been adopted as the 1.2 Combobox design pattern( 2022)

Design Doc Content Template Text

{{Name of combobox}}, combobox

Accessible Name (dynamic): Text + {{Name of Selected list item}} (e.g. Solute: {{Drink Mix}})

Interaction Type: Combobox (i.e., Combobox.ts composed of subcomponents ComboBoxButton.ts (tagName: 'button') and ComboBoxListBox.ts (ariaRole: 'listbox')

Button Label with initial selection:

Listbox list items:

• List Item 1 (e.g., Drink Mix)
• List Item 2 (e.g., Cobalt (II) nitrate)
• List Item 3

(Optional) Help Text:

(Optional) Link to section with object & context responses

(Optional) Design Note: Special things about this combobox, if any.

RectangularRadioButtonGroup

• Source Code and Options
• Number of sims that use this component: 75

No markdown content for RectangularRadioButtonGroup yet.

ToolboxPattern

• Source Code and Options
• Number of sims that use this component: 4

Toolbox Design Pattern

Here’s the when and why we use a toolbox pattern.

• The toolbox pattern is a custom interaction pattern used to group 2 or more tools (e.g., measurement tools). These tools can be added to the Play Area of a simulation for different purposes.
• The tools in the toolbox present as button interactions. They are placed in the PDOM order as single focusable objects (i.e., no grouping behavior yet available on the toolbox).
• The activated tool is visually transformed, receives focus, and becomes draggable with Arrow keys (and alternatives).

Note: This pattern is also referred to as the Creator Pattern.

Aesthetic Considerations

• Toolbox appears in a visually defined space like a outlined box.
• The toolbox and tools usually appear without any visual names, but in some cases visual names appear in addition to the tools (e.g., Circuit Construction Kit: AC).
• Title case is used for text-based tool names.
• An activated tool becomes full size. Depending on input method, the full-sized tool is dragged to a desired placed by the learner (pointer input), or it is placed near the toolbox or automatically in a useful place in the Play Area.

Interaction Design Considerations for Alternative Input

• Ensure the PDOM placement of the activated tool makes sense to the use of the activated tool.
• Ensure focus goes on the activated tool so it can be easily moved once activated.
• Ensure it is not too easy to accidentally return the tool to the tool box when using Alt Input.
• Ensure the Escape key works to return a focused-activated tool to the toolbox.
• Consider sim-specific shortcuts to make using the tool more efficient and effective for Alternative Input users.

Keyboard Interaction & Support

Note: Optional: Sim-specific shortcuts can be designed and implemented to jump a focused-activated tool to useful places in the simulation.

Toolbox Visual Example

• Geometric Optics Visual toolbox with no visual names:

Checkbox as Alternative to the Toolbox Pattern

The checkbox interaction can be used as an alternative to using the toolbox pattern. If a checkbox is used:

1. The Escape key does not work as a shortcut to uncheck the checkbox, and thus hide the activated-focused tool.
2. A tool activated by a checkbox does not need an additional two-step drag interaction. The action of checking the checkbox is the user's intentional activation of the tool. The Arrow keys (or alternatives) are then immediately operable to move the tool. For tools in a toolbox, the pressing of Space or Enter indicates the user's intention in the same way.
3. Like other tools, tools activated by a checkbox need consideration for sim-specific shortcuts to make using the tool more efficient and effective for Alternative Input users.

Description Design Considerations (Future)

• The tool activation step for both the toolbox and the checkbox tool provides the opportunity to give instructions to blind users once description is implemented. The activation step is what was determined to be needed for BASE's Yellow Balloon, Friction's Chemistry Book, and others (Faraday's Law, Gravity Force Lab) where the custom draggable object is already in the Play Area.
• It's these "already-in-the-Play-Area" draggable sim objects that may need to be revisited once the sims that contain these readily available draggable objects get a description feature.

State Descriptions

<h3>Toolbox</h3>
<p>Grab a ruler or marker as needed.</p>
<button>Horizontal Ruler</button>
<button>Vertical Ruler</button>

Responsive Descriptions

• When activated: Added to {{locationInPlayArea}}. Use Arrow keys or W, A, S, or D keys to move {{Horizontal Ruler}}.
• When returned: Back in toolbox.

KeyboardHelpDialog

• Source Code and Options
• Number of sims that use this component: 39

General Design Considerations

• A keyboard help dialog helps guide users with keyboard interaction.
• If an interaction comes first as an interaction in the sim, it should likely come first in the help dialog.

RoundPushButton

• Source Code and Options
• Number of sims that use this component: 133

No markdown content for RoundPushButton yet.

RectangularPushButton

• Source Code and Options
• Number of sims that use this component: 123

No markdown content for RectangularPushButton yet.