Unexpect behavior of pdomOrder.

[pixelzoom]

While working on phetsims/mean-share-and-balance#47 with @marlitas, we were very confused with how pdomOrder was working. Nodes that we did not include in pdomOrder (for example, this.resetAllButton) were being mysteriously tacked onto the end of the traversal order that we were explicitly setting via setPDOMOrder.

@marlitas remembered from a conversation with @jessegreenberg that he said that this is expected behavior, and that "leftover" focusable Nodes are placed at the end of the pdomOrder. @jessegreenberg is that true? It's the first I've heard of this. It's not mentioned in the documentation for ParallelDOM setPDOMOrder. It's not mentioned in alternative-input-quickstart-guide.md. And it's very confusing.

[jessegreenberg]

Yes, that is correct. Everything that is not listed in a PDOM order gets added to the end by default. The documentation is admittedly lengthy but appears here:

In the general case, when an pdom order is specified, it's an array of nodes, with optionally one
element being a placeholder for "the rest of the children", signified by null.
...
The placeholder (null) will get filled in with all direct children that are NOT in any pdomOrder.
If there is no placeholder specified, it will act as if the placeholder is at the end of the order.

So you can do things like

// put myNode first, then use default rendering order
this.pdomOrder = [ myNode ];

// put the ResetAllButton last, behind default rendering order
this.pdomOrder = [ null, resetAllButton ]

// myNode first, resetAllButton last, otherwise default rendering order
this.pdomOrder = [ myNode, null, resetAllButton ]

[pixelzoom]

Questions:

(1) Why is this behavior desirable? I don't understand the advantage of this feature, especially when we've established that (in general) one should not rely on the order of a Node's children, except for scenery layout Nodes.

(2) If I don't want something to be in the traversal order, how do I prevent that?

(3) Should this info be in the quickstart guide?

[jessegreenberg]

Why is this behavior desirable? I don't understand the advantage of this feature, especially when we've established that (in general) one should not rely on the order of a Node's children, except for scenery layout Nodes.

This API predates that decision by a couple of years. I understand it is better for PhET to make the order explicit but I think this behavior is useful, nice to have generally, and not worth removing.

If I don't want something to be in the traversal order, how do I prevent that?

pdomOrder is just for order. You can set focusable to remove from traversal order or pdomVisible to remove entirely from the PDOM (when screen readers are involved).

Should this info be in the quickstart guide?

I added a note in the quickstart guide about the focusable setter. The other features of pdomOrder are too detailed for that guide in my opinion.

[pixelzoom]

... The other features of pdomOrder are too detailed for that guide in my opinion.

I disagree. I've added this to the end of the Traversal Order section:

Potential gotchas:

• ParallelDOM.setPDOMOrder has some interesting quirks, so be sure to read the documentation closely. Of special interest is the behavior of null in the pdomOrder, and what happens to any focuable Nodes that are not explicitly included when setting pdomOrder.
• If you need to augment this.pdomOrder in a subclass, read about the pitfalls
  in Problems encountered when setting pdomOrder #1308.