Preferences dialog lacks consistent UI style.

[pixelzoom]

In #837, Options were folded into the Preferences dialog. In general, the content for the Options dialog was not changed, it was simply passed to the Preferences dialog. The end result is that there are now different UI styles in the Preferences dialog, a bit of a hodge podge.

For example, see Gas Properties. Projector Mode (handled by Preferences dialog) is set using an A/B switch, with a nice description of the preference, and looks like this:

Options specific to Gas Properties used a checkbox instead of an A/B switch, and has no description. It looks like this:

A style guide and some common-code UI components are needed.

PhET can certainly live with this for now, because it's usable. If we didn't have to worry about PhET-iO, this issue would be a "polish". But changing to a consistent UI style in the future will break the PhET-iO API, require migration rules, etc.

[terracoda]

Great points, @pixelzoom. I think it might be better for me to comment in the other issue where we are discussing wording of the "inclusive features".

Perhaps a temporary fix is using a "Sim-specifc Options" subheading here for these types of checkboxes that are being migrated directly from the PhET Menu to the Preferences Menu.

[terracoda]

This issue is also related to #838

[amanda-phet]

Related to this issue, we discovered that the right-aligned toggle switches can look too close to the next column and leads to a very confusing interface.

This doesn't seem to be as problematic in the sims with voicing because there is a string lower down that makes the two columns appear farther apart, but we should still probably handle this column width thing in common code.

Overall, this is contributing to us thinking that a left-aligned toggle switch seems like it would work a lot better in the preferences dialog, and then the toggles will be aligned in every preferences dialog and their placement won't be all over, and the toggle will always be closest to the respective title/thing it is controlling.

[amanda-phet]

Discussed a unified design for the preferences dialog 11/17/22

• When should we use toggles vs. checkboxes?
• How should we display spinners?
• What about aqua radio buttons?

Current toggle paradigm works well in a single-column format with right-aligned toggles.

• Looking at MacOS and Chrome preferences, they have "tabs" (categories) on the left side, and a scrollable single column of preferences (with right-aligned toggles).
• Why don't we have a scrollable preferences dialog? Because we wanted everything visible on the screen and not have something that is hard to find. We'd need to build something in scenery to allow scrolling (scrollPane?) if we want this in the preferences dialog.
• Scrolling might be annoying if it dramatically changes the size of the scroll bar. If there is not enough content to activate the scrollbar we'd want it to not show up. Could possibly have a scrollbar that appears and disappears depending on what is checked.
• Having one column can be hard because certain content may be hidden lower.
• scrolling would need to work with focus traversal

Another inconsistency:

• Sometimes a toggle shows/hides content below, but sometimes it grays out content below.

If a tab has multiple columns, should we make the column widths consistent? Rather than base it on the contents of the column?

• would make to make sure these column widths are responsive, since the preferences dialog can sometimes be really wide (if locales are available).

Different tabs seem to have different types of control

• simulation tab is totally custom
• audio tab is pre-set as two columns
• there needs to be logic for the layout that is responsive and consistent across all sims with preferences dialogs; a template that anyone could put their content into
• there should also be reusable components that give us the look and information that we want (e.g. adding descriptions to preferences)

Immediate concerns:

• lots of sims are on deck to be published with a preferences dialog that is a little wonky. For now, this is ok by @kathy-phet and these sims won't be blocked.
• once we have a unified design, will we have the resources to return to those sims and re-publish them with an updated dialog? @kathy-phet says likely yes, since many of these sims are PhET-iO sims.
• Some sims have the "options" content being moved over to the "simulation" tab, and don't match the style in other dialogs because there isn't an established design.
• @jessegreenberg made a "preferences toggle button" that is a toggle switch under the hood with role=switch. Checkboxes in preferences dialog are special and not the same as the ones in sims- there was a reason for this but we can't remember, possibly related to voicing.

Next steps:

• @marlitas could create reusable components that devs could use to put in simulation tabs based on the look and feel of the audio tab preferences. (could these have the format of "name" and "description" ?)
• @marlitas should dig in to the current preferences components and untangle/document what these special components are (checkbox, toggle button, maybe others).
• might come back to the idea of scrolling/single column as well
• explore the idea of each column having a faint box around them to help define the left and right columns
• need to decide if we are going in the two-column or one-column direction
• @catherinecarter will take a stab at doing some mockups! @arouinfar will pair and be a thought partner.

[terracoda]

Regarding the first action item, I would like for us to use a consistent language for things that require words, i.e. the text that can be recognized by screen readers or delivered via the Voicing feature.

"description" might be too general as everything from the Sim's name in the H1 to a context response that fires as changes happen is a description. It might be useful to call an interactive object's description "help text" if that is the function of the description.

[pixelzoom]

@marlitas After the above changes, I'm seeing something very odd in PreferencesToggleSwitch, and therefore in calculus-grapher ValueControl. PreferencesToggleSwitch is now unrelated to ToggleSwitch -- are you planning to rename PreferencesToggleSwitch? I understand that you are generalizing, but that should start with the name.

[marlitas]

@pixelzoom Yes the rename is happening today. Ran out of time last night. It has now been refactored to take any control in the upper right corner (or wherever we decide in terms of design in the future). This has been done to make preferences components more consistent among sims and easier for developers to use. What was the odd behavior you were seeing? I want to make sure I refactored all cases out properly.

[pixelzoom]

Two things:

• It's odd that all subcomponents of PreferencesToggleSwitch are optional. Shouldn't controlNode at least be required?

• You have several SelfOptions fields that have type null | Node. It guess that works. But it's preferrable to define then as Node, then StrictOmit them in the optionize call, so that the null default value is unnecessary

-   labelNode?: null | Node;
+   labelNode?: Node;

- const options = optionize<PreferencesToggleSwitchOptions, SelfOptions, NodeOptions>()( {
+ const options = optionize<PreferencesToggleSwitchOptions, StrictOmit<SelfOptions, 'labelNode'>, NodeOptions>()( { 

-      labelNode: null,

[marlitas]

It's odd that all subcomponents of PreferencesToggleSwitch are optional. Shouldn't controlNode at least be required?

The hope is that his component will work for all the different use cases a preferences dialog may need. For example, a component may need a title and a control, but there are also moments when it may only need a title and description, or just a title, or a description and a control. Making all of these optional will provide flexibility while maintaining a consistent UI across the different usages. The name PreferencesControl is 100% up for discussion as it does not fully encompass these usages, but it felt like a step in the right direction.

[marlitas]

I updated NumberPlayPreferencesNode to use the new PreferencesControl API. @chrisklus the commits are above if you want to take a look and reach out to me for any questions or concerns.

[chrisklus]

@marlitas and I reviewed the changes in Number Play together. Thanks! Back to @marlitas.

[marlitas]

Reopening, as the work for preferences isn't done here, but it is done for Number Play. :-)

[chrisklus]

Ope, my bad! Forgot this wasn't in a Number Play repo.