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.

[samreid]

As far as I know, YAML doesn't require language support

But it means anyone developing/maintaining binder would need to be able to use YAML properly and the conventions for how to use it in this context.

it's then parsed into JSON.

Why not use JSON?

Additionally, this would allow us to register several components into a single md file.

Why would we want to combine several components into a single MD file? Why not have VerticalAquaRadioButtonGroup.md say "This uses the patterns described in RadioButtons.md" and have a link to RadioButtons.md? That approach seems very scalable, very flexible and doesn't require any overhead.

[jessegreenberg]

In the meeting yesterday we discussed that the experience and UI for binder may be better if we collect common content into single files like in #15 (comment). But we also mentioned that this adds complexity and manual work because now the structure needs to be designed and we will have to come up with values for entries, title, children on a case by case basis. I think we are exploring how this structure might work technically, but after the meeting I don't think we were ready to commit to it yet.

Why not use JSON?

I don't really know how binder works, but I have the same question.

[mbarlow12]

Why not use JSON?

@samreid I misspoke, it's not parsed to JSON but into an object with data and content keys. The first holds another object with key(s) & value(s) outlined in the YAML section, and the latter is the raw markdown that can then be transformeed into HTML.

I suppose it would be possible to have like-named json docs alongside the md files, but 1) I seriously doubt we'll need much metadata and 2) it seems like this still adds similar maintainence concerns but with more files.

Why would we want to combine several components into a single MD file?

The main advantage I see is to allow for more thematic organization of the components that we can configure. There's currently no way that we can group VerticalAquaRadioButtonGroup and RadioButtonGroup together. Additionally, I'm having trouble coming up with another way of handling the original issue @zepumph raised in #15 (comment).

Another advantage I see is that it decouples the documentation organization/presentation from that of the repos. While we can still have component-specific .md files, we wouldn't necessarily be tied to them if necessary. For example, if a scenery node and sun component both fit into a shared category, the YAML configuration would allow for that with minimal upkeep.

[zepumph]

Unassigning, let me know if you need anything else from me.

[terracoda]

Can we simplify by just referring to interactions as:

• Single-State Interactions
• Two-State Interactions
• Multi-State Interactions
• Grouped Interactions
• Customized Interactions

The following two tip sheets that I created for the Description Design Course use these categories to group Interaction Types.

• Tip Sheet - Design Patterns for Multi-State & Customized Interactions
• Tip Sheet - Design Patterns for Single- & Two-State Interactions

[terracoda]

Unassigning myself until we work are able to actively work on binder issues.