Subcomponents need a way to opt out of registering if their Parent component "covers" them

[zepumph]

Example came up in keyboard nav meeting today. AccordionBox uses ExpandCollapseButton, and the custom html for AccordionBox (that includes ECButton in the PDOM is potentially different from the interaction pattern of ExpandCollapseButton itself. How should this look in the style guide?

@terracoda is this summing up what you were wondering about during the meeting?

Notes:

1. @emily-phet noted this is a very a11y specific problem, and we don't really have to worry about this until we want ExpandCollaspseButton (the subcomponent) in the style guide.
2. Even so we may need to handle this in other places, so I thought an issue would be good.

[mbarlow12]

Perhaps ExpandCollapseButton isn't be best example as it probably should be inheriting from another button (there's even a comment in its file and an issue to convert it to a subtype of one of the sun/buttons/). My general thought is that if component x has a certain set of interactions, and a parent component uses it and drastically changes those interactions, then the parent probably shouldn't be using that component.

As to deregistering it

1. I can't think of how we would determine when to include/exclude a component instance based on its context/parent usage.
2. It may still be useful to include such instances to better illustrate the flexibility of some of the components?

[mbarlow12]

From the a11y discussion today, I think it may be useful to handle this in the md files. There are libraries for parsing 'front matter', which is YAML syntax delimited within a md file by three dashes ---. Parsing into a json object is rather straightforward. See https://github.com/jonschlinkert/gray-matter.

In this way, we could register a children tag that would notify the binder code that component x utilizes component y within itself. Additionally, this would allow us to register several components into a single md file.

[mbarlow12]

Here's an example for radio buttons (maybe named RadioButtons.md):

---
components: VerticalAquaRadioButtonGroup, RadioButtonGroup
title: Radio Buttons
children: AquaRadioButton, RadioButtonGroupMember
---

## General Design Considerations
Here’s when and why we use radio button groups:
* Used to group a set of mutually exclusive buttons, known as radio buttons, where only one button in the group may be in a selected state.
* Radio button groups or radio groups, may look like a group of traditional radio buttons, or may look like a group of items that users switch between. In PhET simulations the radio button themselves may be rectangular buttons with images or symbols - we call these “scene selection” radio buttons.

## Aesthetic Considerations
* Label text is succinct and ideally sounds good when read as "selected". For example, in Area Model, the first Area Grid Size radio button might sound like, "10 by 10, selected". In Balloons and Static Electricity, a user may hear, "Show all charges, selected". 
* Occasionally a small icon follows the label text.
* Scene selection style radio buttons generally show the selected button as fully opaque with a thick black stroke, and the unselected buttons have reduced opacity and a thin stroke.
* Focus highlight has a light focus around the group, and a thicker pink focus around the selected item.

## Accessibility Considerations
* The following information is useful for fully communicating the interaction in the non-visual experience.  
  * the name of the radio button in the group that has focus,
  * the state (selected or not selected) of the radio button,
  * the fact that button is in a radiogroup, or in a radio button list,
  * the name of the group, and
  * the number of buttons or options in the group, 
* It is important for a designer to consider upfront if the group's name should be part of the heading outline of the simulation or not. Placing the group's name in the heading outline (Sample HTML 1) gives the group's name more visibility (e.g., findability) in the non-visual experience. If that visibility is not necessary, you could use a `legend` element (Sample HTML 2). 
...
...
...

[zepumph]

That seems so cool! Would the binder build process just support YAML? Or would devs need to do an extra download to support the language?

Tagging @samreid because he too may have thoughts.

[terracoda]

@mbarlow12, I like this solution @mbarlow12, if YAML is support.

[samreid]

Tagging @samreid because he too may have thoughts.

I don't know enough about the problem or proposed solution. I was imagining that (for example) VerticalAquaRadioButtonGroup.md and would have a link like:

See RadioButtons.md [linked]

Not sure whether that would work or how the proposed solution differs. I'm not sure I see the advantage of introducing a different language here.

[mbarlow12]

@zepumph @samreid As far as I know, YAML doesn't require language support, and binder would handle parsing it on its own with the help of the gray-matter library linked above. The conventions are that the initial YAML is ALWAYS first and enclosed within --- characters; it's then parsed into JSON.

The main contents outside the YAML section appear to be returned within a content key, so I'm pretty sure we can then pass that to our marked package to parse the markdown into HTML. In that way, the YAML would only be used for metadata (including categories, tags, or special formatting needs if necessary) within the build process. I'll make a branch in sun and binder to test this out.