Add Tier 1 description features

[jessegreenberg]

In #101 it was decided that we are going to try to add Tier 1 description for trig-tour. That includes

• Accessible names for interactive components
• Help Text for interactive components
• Screen summaries

[jessegreenberg]

I will take a first pass at this to set up the boilerplate then assign to the design team for content.

[jessegreenberg]

OK, the basics are in place as placeholders. Some but not all components are getting the names from the visual text. The a11y view looks something like this:

If that is not helpful or difficult to read let me know and I won't do this again. But I thought this might be helpful as a starting point.

@amanda-phet can you please let me know what content you would like in here? Or feel free to edit https://github.com/phetsims/trig-tour/blob/main/trig-tour-strings_en.json directly. Let me know if optional help text should be deleted or if I missed anything.

[amanda-phet]

Back to @jessegreenberg to implement the design from our last meeting.

[jessegreenberg]

Notes and questions:

Help Text (when collapsed): Expand to show angle measure, coordinates, and trig value.

Is this the design we want for all AcordionBoxes, should this be moved to sun?

I added quadrantProperty to the model to support the dynamic screen summary.

I added valuesExpandedProperty to the TrigTourModel so that we can observe the state of that accordion box for the details description.

I added model values for the sin, cos and tan function values so that they could be read out in the description with the same precision.

I created TrigTourDescriber, to factor out some of the reusable code that describes the values of the simulation. The TrigTourDescriber is now created in the ScreenView, and passed to various view components.

I created a new view component called AngleReadoutValue that manages the angle readout, units, and how many decimals to display - so that this logic could be used by both the visual and the descriptions.

The summary details content is combined into a single sentence. This will support the description content, Voicing statement, and accessibleParagraph - because the second two need to be a single string Property.

Only numerical values are read. When the sim shows special angle fractions, the Voicing and description will read numerical values.

Can we review the strings together to understand the changes and review for i18n goals?

[jessegreenberg]

This is complete and ready for a review. @amanda-phet @terracoda can you please review the behavior on main?

I also asked on slack about reviewing the list in #107 (comment) in a meeting together. It has some questions about behavior, but also has notes about changes made for Tier 1 Description to document changes and scope of work.

[terracoda]

I think this list captures the key things from the notes I posted in slack.

1. Suggested changes to the static play area description:
   An interactive circle with a radius of 1 is centered on a coordinate plane. A movable point on the circle defines an angle theta as the point is rotated counterclockwise or clockwise from the x-axis. A right triangle forms between the radius, the x-axis, and the vertical line from the point to the x-axis. The selected trigonometric function highlights the corresponding side or sides of the triangle being explored inside the circle. Below the circle, a collapsible horizontal graph maps the selected function versus theta. The graph has a corresponding movable point which can go off screen.

No changes to the static control area description!

2. Suggested changes to the "Current Details", too. I think we can write it in the active voice, and i think it makes sense to put the rotation direction first. This significantly shortens the description from 3 paragraphs to 1:

Currently, {{clockwise}} rotation of point on circle forms angle theta. Point on circle is in quadrant {{1}}; Angle theta equals {{50.0°}}; x equals {{0.643}}; y equals {{0.766}}; Sine equals {{0.766}}.

3. ALSO for the last detail above: If it is sine-theta, cosine-theta, or tangent-theta on the screen, shouldn't we say the same in the description, e.g., "Sine-theta equals {{0.766}}."

I was also hoping to easily add a description that describes which colored arrow is highlighted, but I think that is a detail that we can add as part of Tier 2.

4. The repeated description that goes in the expanded Values accordion box panel is now (as suggested above):
   Angle theta equals {{50.0°}}; x equals {{0.643}}; y equals {{0.766}}; Sine equals {{0.766}}.

5. Adding: NOT SURE on this item. Will open a seperate issue. Remove the help text for the graph accordion box. We only need help text for collapsed accordions in the Voicing feature. The aria-state communicates the expanded and collapsed states automatically for Interactive Description. SEE Description/Voicing design pattern for Accordion Box #131 for this item.

6. Add "Graph" to the accessible name of the graph accordion box, or add "Graph" to both the visual and accessible names, if others agree.

   • Cosine Theta versus Theta Graph
   • Sine Theta versus Theta Graph
   • Tangent Theta versus Theta Graph

7. Help text for Point on Circle - add "theta" after angle:

   • Move point on circle to change angle theta. (could use "explore" instead of "change"??)

8. Help text for Trig Functions radio group. Change from "Compare values and graphs of different trig functions."
   - To: "Compare values and representations of different trig functions." OR
   - To: "Choose trig function and compare values and graphs."

9. Where in the PDOM do we put the "Point is off screen!" and can we add the direction since there is an arrow on the screen?

   • I suggest adding the string at the end of the Point on Graph help text?
     • "Move point on graph to change theta. {{Point off screen to right!}}"
     • "Move point on graph to change theta. {{Point off screen to left!}}"

10. Question: Orientation of Point on Circle or Graph:

• Does the point have a numeric value of its own that can be numerically represented? Ignore this question. I think this question can be answered as part of Tier 2 design when we do object responses.

11. My biggest design question is around the Current Details and the Values Accordion Box content. The content in the Values Accordion Box is technically a set of dynamic state descriptions, which are technically not part of Tier 1. My initial thought was that we include that content under the Voicing Details button and not do a reading block (in spite of it being very prominent on-screen text).

Given @kathy-phet desire (very valiant and admirable) and current direction to voice the Values Accordion Box content, I think we need to do 2 things to make sure we are not swaying from a good design process:

• Firstly, recognize that this may not technically be Tier 1 Voicing, and at the same time ensure we align the descriptions delivered in both features. To do this I suggest:

  • we design the strings to be as close to the visual representation as possible,
  • for voicing, use 3 reading blocks to deliver the content
  • for interactive description, use 3 accessible paragraphs to deliver the content.

• Secondly, simplify the Current Details and provide something slightly different and still very supportive of making sense of those values. For example, we could provide something super simple about the current set up:

  • Currently, circle and graph display {{cosine}} theta. A {{clockwise}} rotation of point on circle forms an angle of {{50.0 degrees}}. Point on circle is in quadrant {{1}} with x-y coordinates of {{0.643}} and {{0.766}}. On graph cosine theta equals {{0.643}}.

Or maybe this is slightly better:
- Currently, circle and graph display {{cosine}} theta. A {{clockwise}} rotation of point on circle puts the point in quadrant {{1}} with an angle of {{50.0 degrees}}. The point's x-y coordinates are {{0.643}} by {{0.766}}. On graph, cosine theta is plotted at {{0.643}}.

I hope this makes sense.

[terracoda]

@jessegreenberg, I will open a separate issue about the description and voicing design pattern for accordion boxes. I need to check what i have done in the past. See #131

[jessegreenberg]

Is this the design we want for all AcordionBoxes, should this be moved to sun?

To be continued in #131.

Only numerical values are read. When the sim shows special angle fractions, the Voicing and description will read numerical values.

We discussed this - It is unfortunate. We may create patterns that read the values in a general way. We also discussed having sim-specific patterns to make it simple to enumerate all values. We will need to make a call on whether we can spend time on it now.

[terracoda]

12. Missing description of Easter Egg! - This event is a fun event. The responsive description (context response) for it is definitely part of Tier 2. Since the event only occurs are at Max number of rotations, it makes sense to me to add or pre-pend a description in the current details (both Interactive Description and Voicing) when the sim hits this state.

The description suggested above with some additions.

• Currently, {{theta symbols and stars dance around a dizzy PhET girl as}} circle and graph display {{cosine}} theta. A {{max}} {{clockwise}} rotation of point on circle puts the point in quadrant {{3}} with an angle of {{-9090.0 degrees}}. The point's x-y coordinates are {{0.000}} by {{-1.000}}. On graph, cosine theta is plotted at {{0.000}}. {{Point off screen to the left!}}

• {{Theta symbols and stars dance around a dizzy PhET girl!}} Currently, circle and graph display {{cosine}} theta. A {{max}} {{clockwise}} rotation of point on circle puts the point in quadrant {{3}} with an angle of {{-9090.0 degrees}}. The point's x-y coordinates are {{0.000}} by {{-1.000}}. On graph, cosine theta is plotted at {{0.000}}. {{Point off screen to the left!}}

[amanda-phet]

Discussion 1/23/25 (@terracoda added bold text to initial bullet items after meeting):

• Punt on putting the "Point off screen" text in the PDOM. This feels outside of tier 1 description.
• If we want this sim to be a tier 1 voicing example, we need to decide if that includes reading blocks [dynamic state descriptions]. If tier 1 voicing has reading blocks, then tier 1 description would need to include that same content in the PDOM (maybe). Would be simpler to not include reading blocks in tier 1 voicing if we want this to be truly scalable.
• Big picture question: do Tier 1 voicing and Tier 1 description need to be as aligned as possible? Need to iron out tier 1 requirements.
• After discussion with @kathy-phet regarding tier 1 nuances we might move some content around to align with finalized tier 1 guidelines.

Decisions to implement:

(1) Change the current details. We will not have the sentence that is dependent on the Values accordion box being open/closed. Instead, use this in all cases:

Currently, {{cosine}} is selected. A {{clockwise}} rotation of point on circle forms angle theta. Point on circle is in quadrant {{1}}.

(2) Change the description of the Play Area:

An interactive circle with a radius of 1 is centered on a coordinate plane. A movable point on the circle defines an angle theta as the point is rotated counterclockwise or clockwise from the x-axis. A right triangle forms between the radius, the x-axis, and a vertical line from the point to the x-axis. The selected trigonometric function highlights the corresponding side or sides of the triangle being explored inside the circle. Below the circle, a collapsible graph plots the selected function versus theta. The graph has a corresponding movable point which can go off screen.

(3) Add "Graph" to the accessible name of the graph accordion box, or add "Graph" to both the visual and accessible names, if others agree.

• Cosine Theta versus Theta Graph
• Sine Theta versus Theta Graph
• Tangent Theta versus Theta Graph

(4) Change help text for point on circle:

Move point on circle to change theta.

[jessegreenberg]

Changes in this list have been made. @terracoda @amanda-phet can you please review?