// Copyright 2017-2019, University of Colorado Boulder

/**
 * IO type for Focus
 *
 * @author Sam Reid (PhET Interactive Simulations)
 * @author Jesse Greenberg (PhET Interactive Simulations)
 */
define( function( require ) {
  'use strict';

  // modules
  var Focus = require( 'SCENERY/accessibility/Focus' );
  var ObjectIO = require( 'TANDEM/types/ObjectIO' );
  var scenery = require( 'SCENERY/scenery' );
  var validate = require( 'AXON/validate' );

  class FocusIO extends ObjectIO {

    /**
     * Convert the focus region to a plain JS object for serialization.
     * @param {Object} focus - the focus region which has {display,trail}
     * @returns {Object} - the serialized object
     * @override
     */
    static toStateObject( focus ) {
      validate( focus, this.validator );
      var phetioIDs = [];
      focus.trail.nodes.forEach( function( node, i ) {

        // If the node was PhET-iO instrumented, include its phetioID instead of its index (because phetioID is more stable)
        if ( node.isPhetioInstrumented() ) {
          phetioIDs.push( node.tandem.phetioID );
        }
      } );

      return {
        focusedObject: phetioIDs
      };
    }
  }

  FocusIO.validator = { valueType: Focus };
  FocusIO.documentation = 'A IO type for the instance in the simulation which currently has keyboard focus. FocusIO is ' +
                          'serialized into a `focusedObject` that is a list of PhET-iO elements, from parent-most to ' +
                          'child-most cooresponding to the PhET-iO element that was instrumented.';
  FocusIO.typeName = 'FocusIO';
  ObjectIO.validateSubtype( FocusIO );

  return scenery.register( 'FocusIO', FocusIO );
} );
@@ -1146,21 +1146,28 @@
  focused
-Objec
+PhetioElemen
 t: pheti
@@ -1406,22 +1406,47 @@
 to a
- %60focusedObjec
+nd Object with key %60focusedPhetioElemen
 t%60 t
@@ -1483,28 +1483,8 @@
 nts,
- from parent-most to
  ' +
@@ -1511,16 +1511,36 @@
        '
+from parent-most to 
 child-mo

update documentation, https://github.com/phetsims/scenery/issues/866