Rename aria-valuetext and context response functions in AccessibleValueHandler

[jessegreenberg]

This will align with the design team terminoligy and the design document. It is create that it is prefixed with accessible and matches the other "high level" API functions (like accessibleName).

It is a creator function so it might have been prefixed with "create" like createAccessibleObjectResponse. But it seems very valuable to make all of these options start with accessible.

We also want to rename pdomCreateContextResponseAlert -> accessibleContextResponse for the same reasons.

This is part of phetsims/membrane-transport#10

[jessegreenberg]

Also on slack recently, @marlitas said

I was surprised to see that ariaValueText accepts a TReadOnlyProperty but that gets overridden by the provided valueProperty in AccessibleSlider. Is this expected?

Lets improve the API and at least exclude ariaValueText from options that AccessibleValueHandler can take.

[jessegreenberg]

In phetsims/scenery#1715 we are removing the aria-valuetext setter, which is related to #929 (comment) so that it is not part of the public API.

[jessegreenberg]

I am considering this API change to replace pdomCreateAriaValueText and pdomCreateContextResponseAlert.

  /**
   * Pattern string for the accessibleObjectResponse when the value changes.
   * Must include SunConstants.VALUE_NAMED_PLACEHOLDER or SunConstants.VALUE_NUMBERED_PLACEHOLDER.
   * Mutually exclusive with accessibleObjectResponse.
   */
  accessibleObjectResponsePattern?: TReadOnlyProperty<string> | string;

  /**
   * Number of decimal places for the accessibleObjectResponse value.
   * If null, the full value is displayed.
   * Mutually exclusive with accessibleObjectResponse.
   */
  accessibleObjectResponseDecimalPlaces?: number | null;

  /**
   * Function or string or StringProperty for the accessibleObjectResponse on value change.
   * Use for custom or qualitative messages (e.g., "low", "medium", "high").
   * Mutually exclusive with accessibleObjectResponsePattern and accessibleObjectResponseDecimalPlaces.
   */
  accessibleObjectResponse?: TAlertable | CreateTextFunction<number | null>;

  /**
   * String or function or StringProperty for the accessible context response, announced after user interaction ends.
   * Receives the most recent value.
   */
  accessibleContextResponse?: TAlertable | CreateTextFunction<number | null>;

[pixelzoom]

Where is pdomDependencies addressed in the proposed API?

[jessegreenberg]

I want accessibleObjectResponse to be able to take a TReadonlyProperty<string> (a constituent type of TAlertable). So for example:

      accessibleObjectResponse: new DerivedProperty( [
        evaporator.evaporationRateProperty,
        BLLPreferences.beakerUnitsProperty,
        BeersLawLabStrings.pattern[ '0value' ][ '1unitsStringProperty' ],
        BeersLawLabStrings.a11y.unitsDescription.litersPerSecondStringProperty,
        BeersLawLabStrings.a11y.unitsDescription.millilitersPerSecondStringProperty
      ], ( value, units, stringPattern, litersPerSecondString, millilitersPerSecondString ) => {
        const valueString = ( units === 'liters' ) ?
                            toFixed( value, BLLConstants.DECIMAL_PLACES_EVAPORATION_RATE_LITERS_PER_SECOND ) :
                            toFixed( value * 1000, BLLConstants.DECIMAL_PLACES_EVAPORATION_RATE_MILLILITERS_PER_SECOND );

        const unitsString = ( BLLPreferences.beakerUnitsProperty.value === 'liters' ) ?
                      BeersLawLabStrings.a11y.unitsDescription.litersPerSecondStringProperty.value :
                      BeersLawLabStrings.a11y.unitsDescription.millilitersPerSecondStringProperty.value;

        return StringUtils.format( BeersLawLabStrings.pattern[ '0value' ][ '1unitsStringProperty' ].value, valueString, unitsString );
      } ),

Or with a fluent pattern you could do something like this

      accessibleObjectResponse: BeersLawLabFluent.a11y.evaporationSlider.accessibleObjectResponse.createProperty( {
        value: new DerivedProperty(
          [ BLLPreferences.beakerUnitsProperty, evaporator.evaporationRateProperty.value ],
          ( units, value ) => {
            const unitsValue = ( units === 'liters' ) ? value : value * 1000;
            return toFixed( unitsValue );
          }
        ),
        units: BLLPreferences.beakerUnitsProperty
      } ),

[jessegreenberg]

I started on this this morning but need to switch to other work so here is a patch:

Details

Subject: [PATCH] Add isLocaleChanging so that we can opt out of work while many LocalizedStringProperties change at once, see https://github.com/phetsims/chipper/issues/1611
---
Index: js/accessibility/AccessibleValueHandler.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/js/accessibility/AccessibleValueHandler.ts b/js/accessibility/AccessibleValueHandler.ts
--- a/js/accessibility/AccessibleValueHandler.ts	(revision 62a3614a7aeb4b39aeb23eed7294ee1cc6eb2f90)
+++ b/js/accessibility/AccessibleValueHandler.ts	(date 1753802004308)
@@ -16,11 +16,15 @@
  * @author Jesse Greenberg (PhET Interactive Simulations)
  */
 
+// NOTES:
+// deleting pdomCreateAriaValueText
+// deleting pdomDependencies ( replaced by derived property )
+
 import DynamicProperty from '../../../axon/js/DynamicProperty.js';
-import Multilink, { type UnknownMultilink } from '../../../axon/js/Multilink.js';
+import { type UnknownMultilink } from '../../../axon/js/Multilink.js';
 import Property from '../../../axon/js/Property.js';
 import type TProperty from '../../../axon/js/TProperty.js';
-import type TReadOnlyProperty from '../../../axon/js/TReadOnlyProperty.js';
+import TReadOnlyProperty, { isTReadOnlyProperty } from '../../../axon/js/TReadOnlyProperty.js';
 import type Range from '../../../dot/js/Range.js';
 import { clamp } from '../../../dot/js/util/clamp.js';
 import { equalsEpsilon } from '../../../dot/js/util/equalsEpsilon.js';
@@ -35,7 +39,6 @@
 import { eventCodeToEnglishString } from '../../../scenery/js/accessibility/EnglishStringToCodeMap.js';
 import KeyboardUtils from '../../../scenery/js/accessibility/KeyboardUtils.js';
 import { type PDOMValueType } from '../../../scenery/js/accessibility/pdom/ParallelDOM.js';
-import PDOMUtils from '../../../scenery/js/accessibility/pdom/PDOMUtils.js';
 import Voicing, { type TVoicing, type VoicingOptions } from '../../../scenery/js/accessibility/voicing/Voicing.js';
 import HotkeyData from '../../../scenery/js/input/HotkeyData.js';
 import type PDOMPointer from '../../../scenery/js/input/PDOMPointer.js';
@@ -46,7 +49,8 @@
 import type Node from '../../../scenery/js/nodes/Node.js';
 import { type NodeOptions } from '../../../scenery/js/nodes/Node.js';
 import DelayedMutate from '../../../scenery/js/util/DelayedMutate.js';
-import Utterance from '../../../utterance-queue/js/Utterance.js';
+import { ResolvedResponse } from '../../../utterance-queue/js/ResponsePacket.js';
+import Utterance, { AlertableNoUtterance, TAlertable } from '../../../utterance-queue/js/Utterance.js';
 import type UtteranceQueue from '../../../utterance-queue/js/UtteranceQueue.js';
 import sun from '../sun.js';
 import AccessibleValueHandlerHotkeyDataCollection from './AccessibleValueHandlerHotkeyDataCollection.js';
@@ -65,6 +69,8 @@
 // Signature for the onInput call. See options for documentation.
 type OnInputFunction = ( event: SceneryEvent, oldValue: number ) => void;
 
+type ValueTextObjectResponse = ResolvedResponse | CreateTextFunction<number | null>;
+
 type CreateTextFunction<M extends ( number | null ) | ( number )> = {
 
   /**
@@ -80,6 +86,10 @@
   reset?: () => void;
 };
 
+function isCreateTextFunction<M extends number | null>( fn: IntentionalAny ): fn is CreateTextFunction<M> {
+  return typeof fn === 'function';
+}
+
 export type VoicingOnEndResponseOptions = {
 
   // Should the Voicing response be spoken if the interaction does not change the value?
@@ -109,11 +119,13 @@
   'pdomMapPDOMValue',
   'pdomMapValue',
   'pdomRepeatEqualValueText',
-  'pdomCreateAriaValueText',
+
+  'accessibleObjectResponse',
+  'accessibleContextResponse',
+
   'pdomCreateContextResponseAlert',
   'contextResponsePerValueChangeDelay',
   'contextResponseMaxDelay',
-  'pdomDependencies',
   'voicingOnEndResponseOptions'
 ];
 
@@ -197,12 +209,7 @@
    */
   pdomRepeatEqualValueText?: boolean;
 
-  /**
-   * aria-valuetext creation function, called when the valueProperty changes.
-   * This string is read by AT every time the slider value changes. This is often called the "object response"
-   * for this interaction.
-   */
-  pdomCreateAriaValueText?: CreateTextFunction<number | null>;
+  accessibleObjectResponse?: ValueTextObjectResponse;
 
   /**
    * Create content for an alert that will be sent to the utteranceQueue when the user finishes interacting
@@ -232,12 +239,6 @@
   // silence before the alert is spoken.
   contextResponseMaxDelay?: number;
 
-  /**
-   * List the dependencies this Node's PDOM descriptions have. This should not include the valueProperty, but
-   * should list any Properties whose change should trigger a description update for this Node.
-   */
-  pdomDependencies?: TReadOnlyProperty<IntentionalAny>[];
-
   // Only provide tagName to AccessibleValueHandler to remove it from the PDOM, otherwise, AccessibleValueHandler
   // sets its own tagName.
   tagName?: null;
@@ -261,14 +262,11 @@
   pdomMapPDOMValue: ( ( value: number ) => number );
   pdomMapValue: ( ( newValue: number, previousValue: number ) => number );
   pdomRepeatEqualValueText: boolean;
-  pdomCreateAriaValueText: CreateTextFunction<number | null>;
+  accessibleObjectResponse: TAlertable | CreateTextFunction<number | null>;
   pdomCreateContextResponseAlert: CreateTextFunction<number> | null;
   contextResponsePerValueChangeDelay: number;
   contextResponseMaxDelay: number;
   voicingOnEndResponseOptions: VoicingOnEndResponseOptions;
-  setPDOMDependencies( dependencies: TReadOnlyProperty<IntentionalAny>[] ): void;
-  getPDOMDependencies(): TReadOnlyProperty<IntentionalAny>[];
-  pdomDependencies: TReadOnlyProperty<IntentionalAny>[];
   alertContextResponse(): void;
   reset(): void;
   getAccessibleValueHandlerInputListener(): TInputListener;
@@ -324,8 +322,6 @@
       // A reference to the current value of the aria-valuetext.
       private _ariaValueText = '';
 
-      private _pdomDependencies: TReadOnlyProperty<IntentionalAny>[] = [];
-
       // track previous values for callbacks outside of Property listeners
       private _oldValue: number | null = null;
 
@@ -365,7 +361,7 @@
       // key is the event.code for the range key, value is whether it is down
       private _rangeKeysDown: Record<string, boolean> = {};
       private _pdomMapPDOMValue: ( ( value: number ) => number ) = _.identity;
-      private _pdomCreateAriaValueText: CreateTextFunction<number | null> = toString; // by default make sure it returns a string
+      private _accessibleObjectResponse: ValueTextObjectResponse = null;
       private _dependenciesMultilink: UnknownMultilink | null = null;
       private _pdomRepeatEqualValueText = true;
 
@@ -450,9 +446,6 @@
 
         this._valueOnStart = valueProperty.value;
 
-        // be called last, after options have been set to `this`.
-        this.invalidatePDOMDependencies();
-
         // listeners, must be unlinked in dispose
         const enabledRangeObserver = this.invalidateEnabledRange.bind( this );
         this._enabledRangeProperty.link( enabledRangeObserver );
@@ -476,6 +469,10 @@
           this._enabledRangeProperty.unlink( enabledRangeObserver );
           this._valueProperty.unlink( valuePropertyListener );
 
+          if ( isTReadOnlyProperty( this.accessibleObjectResponse ) ) {
+            this.accessibleObjectResponse.unlink( this._pdomValueTextUpdateListener );
+          }
+
           if ( providedOptions.reverseAlternativeInput ) {
             assert && assert(
               this._valueProperty instanceof DynamicProperty,
@@ -486,7 +483,6 @@
 
           this._dependenciesMultilink && this._dependenciesMultilink.dispose();
           this._panTargetNode = null;
-          this._pdomDependencies = [];
         };
       }
 
@@ -570,14 +566,22 @@
         return this._pdomRepeatEqualValueText;
       }
 
-      public set pdomCreateAriaValueText( value: CreateTextFunction<number | null> ) {
-        this._pdomCreateAriaValueText = value;
+      public set accessibleObjectResponse( value: ValueTextObjectResponse ) {
+
+        // unlink the old listener
+        if ( isTReadOnlyProperty( this._accessibleObjectResponse ) ) {
+          this._accessibleObjectResponse.unlink( this._pdomValueTextUpdateListener );
+        }
+
+        this._accessibleObjectResponse = value;
 
-        this.invalidateAriaValueText();
+        if ( isTReadOnlyProperty( this._accessibleObjectResponse ) ) {
+          this._accessibleObjectResponse.link( this._pdomValueTextUpdateListener );
+        }
       }
 
-      public get pdomCreateAriaValueText(): CreateTextFunction<number | null> {
-        return this._pdomCreateAriaValueText;
+      public get accessibleObjectResponse(): AlertableNoUtterance | CreateTextFunction<number | null> {
+        return this._accessibleObjectResponse;
       }
 
       public set pdomCreateContextResponseAlert( value: CreateTextFunction<number> | null ) {
@@ -644,46 +648,29 @@
         this.inputValue = mappedValue;
       }
 
-      private invalidatePDOMDependencies(): void {
-
-        // dispose the previous multilink, there is only one set of dependencies, though they can be overwritten.
-        this._dependenciesMultilink && this._dependenciesMultilink.dispose();
-
-        this._dependenciesMultilink = Multilink.multilinkAny( this._pdomDependencies.concat( [ this._valueProperty ] ), this._pdomValueTextUpdateListener );
-      }
-
-      /**
-       * There are some features of AccessibleValueHandler that support updating when more than just the valueProperty
-       * changes. Use this method to set the dependency Properties for this value handler. This will blow away the
-       * previous list (like Node.children).
-       */
-      public setPDOMDependencies( dependencies: TReadOnlyProperty<IntentionalAny>[] ): void {
-        assert && assert( !dependencies.includes( this._valueProperty ),
-          'The value Property is already a dependency, and does not need to be added to this list' );
-
-        this._pdomDependencies = dependencies;
-
-        this.invalidatePDOMDependencies();
-      }
-
-      public getPDOMDependencies(): TReadOnlyProperty<IntentionalAny>[] {
-        return this._pdomDependencies;
-      }
-
-      public set pdomDependencies( value: TReadOnlyProperty<IntentionalAny>[] ) {
-        this.setPDOMDependencies( value );
-      }
-
-      public get pdomDependencies(): TReadOnlyProperty<IntentionalAny>[] {
-        return this.getPDOMDependencies();
-      }
-
       private _updateAriaValueText( oldPropertyValue: number | null ): void {
-        const mappedValue = this._getMappedValue();
+
+        let unwrappedValue = '';
+        if ( isCreateTextFunction( this._accessibleObjectResponse ) ) {
+          const createdValue = this._accessibleObjectResponse( this._getMappedValue(), this._valueProperty.value, this._valueOnStart );
 
-        // create the dynamic aria-valuetext from pdomCreateAriaValueText.
-        const newAriaValueTextValueType = this._pdomCreateAriaValueText( mappedValue, this._valueProperty.value, oldPropertyValue );
-        let newAriaValueText = PDOMUtils.unwrapStringProperty( newAriaValueTextValueType )!;
+          if ( createdValue === null ) {
+            unwrappedValue = '';
+          }
+          if ( isTReadOnlyProperty( createdValue ) ) {
+            unwrappedValue = createdValue.value;
+          }
+        }
+        else if ( isTReadOnlyProperty( this._accessibleObjectResponse ) ) {
+          const propertyValue = this._accessibleObjectResponse.value;
+          unwrappedValue = propertyValue === null ? '' : propertyValue.toString();
+        }
+        else {
+          const serializedResponse = this._accessibleObjectResponse;
+          unwrappedValue = serializedResponse === null ? '' : serializedResponse.toString();
+        }
+
+        let newAriaValueText = unwrappedValue;
 
         // eslint-disable-next-line phet/no-simple-type-checking-assertions
         assert && assert( typeof newAriaValueText === 'string' );
@@ -765,8 +752,12 @@
       public reset(): void {
 
         // reset the aria-valuetext creator if it supports that
-        this._pdomCreateAriaValueText.reset && this._pdomCreateAriaValueText.reset();
-        this._pdomCreateContextResponseAlert && this._pdomCreateContextResponseAlert.reset && this._pdomCreateContextResponseAlert.reset();
+        if ( isCreateTextFunction( this._accessibleObjectResponse ) ) {
+          this._accessibleObjectResponse.reset && this._accessibleObjectResponse.reset();
+        }
+        if ( isCreateTextFunction( this._pdomCreateContextResponseAlert ) ) {
+          this._pdomCreateContextResponseAlert.reset && this._pdomCreateContextResponseAlert.reset();
+        }
 
         this._timesChangedBeforeAlerting = 0;
         // on reset, make sure that the PDOM descriptions are completely up to date.
Index: js/demo/components/demoSlider.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/js/demo/components/demoSlider.ts b/js/demo/components/demoSlider.ts
--- a/js/demo/components/demoSlider.ts	(revision 62a3614a7aeb4b39aeb23eed7294ee1cc6eb2f90)
+++ b/js/demo/components/demoSlider.ts	(date 1753796008574)
@@ -7,6 +7,8 @@
  */
 
 import BooleanProperty from '../../../../axon/js/BooleanProperty.js';
+import DerivedProperty from '../../../../axon/js/DerivedProperty.js';
+import PatternStringProperty from '../../../../axon/js/PatternStringProperty.js';
 import Property from '../../../../axon/js/Property.js';
 import stepTimer from '../../../../axon/js/stepTimer.js';
 import type Bounds2 from '../../../../dot/js/Bounds2.js';
@@ -42,6 +44,10 @@
 
   const enabledRangeProperty = new Property( new Range( 0, 100 ) );
 
+  const stringProperty = new Property( 'The new value is {{value}}' );
+  const objectResponse = new PatternStringProperty( stringProperty, {
+    value: property
+  } );
   let slider: Slider;
   if ( orientation === 'horizontal' ) {
     slider = new HSlider( property, range, optionize<SunDemoOptions, EmptySelfOptions, HSliderOptions>()( {
@@ -55,11 +61,17 @@
       enabledRangeProperty: enabledRangeProperty,
 
       // pdom
-      labelContent: 'Horizontal Slider',
-      descriptionContent: 'This is a description of the horizontal Slider.',
+      accessibleName: 'Horizontal Slider',
+      accessibleHelpText: 'This is a description of the horizontal Slider.',
+      accessibleObjectResponse: objectResponse,
 
       phetioEnabledPropertyInstrumented: false
     }, options ) );
+
+    let i = 0;
+    window.setInterval( () => {
+      stringProperty.value = `The values is {{value}} and it changed ${i++} times`;
+    }, 500 );
   }
   else {
     slider = new VSlider( property, range, optionize<SunDemoOptions, EmptySelfOptions, HSliderOptions>()( {