Revise Settings dialog according to new UX design

[tjcouch-sil]

User Story
As a user, I want a more organized and intuitive settings interface, so that I can easily navigate, find, and manage settings for different extensions and projects.

Description

• Implement sidebar hierarchy - extension dropdown with each of that extension's settings groups under its dropdown
• Put all of the settings in one dialog (just UI side of this work)
• Add support for receiving a project id and only showing settings for that project id (see s/r webview, delivers different UI based on a boolean)
• Put all of one extension's setting groups on the same page in cards. Clicking a setting group in the sidebar would scroll to that group
• Use Switch instead of Checkbox
• Many other small adjustments and tweaks

Implementation idea
See the S/R web view for an example of delivering different UI based on a boolean, we could do something similar for receiving a project id and only showing settings for that project id.

See the links below for UX design doc and mockup:

Platform Settings – FigJam

Combined Settings – v0 by Vercel

[tjcouch-sil]

Fill this issue out (or make multiple) when UX gives us their design to implement for epic 13

[tjcouch-sil]

Some notes from the UX presentation:

• Command to open settings needs to be able to accept argument for specific setting to show. Argument for focus mode
  • Do we need to be able to focus setting groups?
  • UX undecided: only one settings dialog, add back/forward buttons
• Extension dev adds buttons to web view toolbar - probably separate issue as not super closely related to settings. Probably fits more in the tab nav epic
• Potentially add way to show one setting component in a modal in app toolbar (dark mode combobox)
  • Sounds like UX hasn't quite decided on this either, so maybe wait on implementing. UX can probably let us know what they think
• Focus mode in settings dialog

[Sebastian-ubs]

We just had sprint meeting and managed to clarify on the following:

• ux is not thinking about which settings to implement first, as dev will be doing this already*
• ux will think about the overall settings hierarchy again (which entries should appear there in which order) + other small adjustments: https://github.com/paranext/ux/issues/152
• ux will timebox a design for settings search or filtering: https://github.com/paranext/ux/issues/149
• ux may continue to think about a user settings menu on the toolbar or postpone it: https://github.com/paranext/ux/issues/109
• tab nav content and tab nav menu are out of scope for this and part of https://github.com/paranext/roadmap/issues/15
• "focus mode" is not a priority
• command menu (global search) is not a priority
• showing one setting in a modal is not a priority
• designing components for specific settings is not a priority
• matching pt9 settings with potential new names is not a priority

*ux wants to be included into how to name these settings

[tjcouch-sil]

Issues to write (@jolierabideau will write them up. Thanks!):

• Revise Settings dialog according to new UX design
  • Implement sidebar hierarchy - extension dropdown with each of that extension's setting groups under its dropdown
  • Put all the project settings in with the settings and make it all one dialog
    • Add support for receiving a project id and only showing settings for that project id
  • Put all of one extension's setting groups on the same page in cards. Clicking a setting group in the sidebar would scroll to that group
  • Use Switch instead of checkbox for booleans
  • Many other smaller adjustments and tweaks
• Add Language dropdown to settings
  • Investigate possible language dropdown someone in SIL has already made
  • Make sure you can select multiple languages and type your own language code in
  • Shadcn combobox is probably a good start if SIL doesn't have a fitting one
  • Add this component to the settings as a special case for the specific settings that handle language? Look at the data type and use this if the setting default value is an array of strings that includes the string 'en'...?
• Add ability to specify a specific setting when opening settings dialog
  • Add parameter to open settings dialog and open project settings dialog commands that is a setting key. When the settings dialog opens, navigate to that key.
• Sync user settings so a user's settings follow them around between computers
  • Create a settings server for storing settings or use the Paratext Registry's existing means
    • There are concerns this may strain the Paratext Registry. How should we go about investigating such concerns and making this decison?
  • Add something to the settings schema to indicate whether the setting should be synced

Defer

• Organizing existing settings - core and UX probably need to talk about what we want extensions to be able to do as the design seems to include organizational capabilities that are not possible right now such as mingling settings between extensions. This has not been settled and will need to wait til another time
• Particular new settings and special components for settings - particular settings can hopefully wait til we implement them, and components probably should wait til extensions can provide components to edit settings
• Settings search - not settled
• Toolbar quick-access settings - not settled/priority
• Focus mode - not priority
• Command palette - not settings / not priority
• Web view tab nav buttons from extensions - not settings / not priority

UX team, please let us know when these not settled things are settled. We can work out where to put them.

Regarding priorities, would you like to create new issues and put them on future epics where they are appropriate priorities? Or want to wait until you have finished designs to figure out what you want to do?

Important links:

Platform Settings – FigJam

Combined Settings – v0 by Vercel

[Sebastian-ubs]

Thanks TJ.

I have a question regarding:

mingling settings between extensions

I've not seen or intended this. Can you give an example? Imho there are only separate pages like "my crazy extension", "custom toolbar buttons extension" and under project maybe things like "project plan", "checks configuration", "Emoji Reactions".

The only mingling I could think of is we have not thought through if extensions should be able to add sections to "display" and "behavior" or only below those. Maybe "scroll with other apps" is something that would come from an extension?? Also we have not been clear about where bcv settings would end up. Or is "highlight current verse" an extension setting of the bundled editor extension and so needs to go elsewhere?

What is missing in the current design (only in case we want to make those configurable) is

• a central place for keyboard shortcuts that includes extensions

---

For the small adjustments, search and toolbar we will let you know as soon as possible (probably in this order).

---

Yes for the "not a priority" things we should create tasks (where not yet done) and move them to a new or existing settings epic. let's decide this in the next roadmap meeting.

[tjcouch-sil]

@Sebastian-ubs Essentially there are three levels of hierarchy possible right now:

1. Extension/Core Name
2. Extension/Core Setting Group
3. Extension/Core Setting

Anything under one of these items in the hierarchy must necessarily be owned by the same extension/core. So core and extension settings cannot intermingle in any way; they are all completely separated from one another.

The same goes for project settings.

Regarding normal settings, there are some somewhat reasonable equivalents in the v0 preview. You can kinda think of it as the following:

1. Extension/Core Name: "General"
2. Extension/Core Setting Group: Display (behavior, internet, my crazy extension, and custom toolbar buttons extension are all also setting groups of this same "general" extension/core name, but I'm not going to focus on them in item 3)
3. Extension/Core Setting: Interface Language, Theme, Scroll with other apps, Highlight current verse

The problem is that "General" has stuff in it that looks like it would be contributed by core and by extensions. If "General" is the label we put for Core Name, then every setting group and setting under it must be contributed by core and not by an extension. So then you could have another top-level hierarchical item called "My crazy extension" that would have a setting group in it that would have settings in it.

Project settings are a bit trickier. It looks like you also have three levels of hierarchy in project settings, but you display them differently:

1. Extension/Core Name: "Project Properties" (other examples are "Project Plan", "User permissions")
2. Extension/Core Setting Group: General (Books, Associations, Notes, Advanced are the others, but I won't focus on them in item 3)
3. Extension/Core Setting: Full Name, Short Name, Copyright, Language, Versification, Type of Project, Based on, Registration

These levels show up differently. All the item 2s for each item 1 are shown all at the same time on the same page. But the item 2s are not shown in the sidebar.

I used my best interpretive skills here and decided to write the UI revision instructions as basically the following for now:

1. Show extension/core names in sidebar and at top of the page (only show one extension/core in the page at a time)
2. Show extension/core setting groups in sidebar under the appropriate extension/core names and show them all in the page. When you click a setting group in the sidebar, scroll to that group in the page
3. Show all extension/core settings for each group in a card in that group

We can discuss and adjust the display of this hierarchical structure as desired. Larger organizational changes will take more planning and adjustment.

[merchako]

Having not talked to @Sebastian-ubs and @allisonparkk , I believe Checkbox vs Switch is not an intentional design detail at this point. It's just what v0's AI came up with.

Update: Apparently it was intentional! Switches are appropriate for settings that take effect immediately. Checkboxes are better for settings that are part of a form that needs to be submitted.

[Sebastian-ubs]

Hi @tjcouch-sil, as we are working on smaller style adjustments, the current (in progress) version is this: https://b_lyq3fteaicn.v0.build/
Maybe that helps with a clearer understanding. IMHO "General" is NOT supposed to be a name, but the place where all not-project-related settings will end up in.

I have added a drawing with questions to the FigJam. Feel free to comment here or there

The content is not final: wording of names, groups and settings and where to put which in is not yet decided.
Alignment of setting labels (on top or right aligned in front of the setting) in the v0 is not final.

[Sebastian-ubs]

[Sebastian-ubs]

by the way: did you know you could install the v0 directly into a project (ideally into platform-bible-react)?
After clicking the "v0" button, there is a "Add to codebase" button.

Of course this code needs to be adapted (split into components, data moved out), but can save some time.

You might however want to wait until we finished

• https://github.com/paranext/ux/issues/152
  and maybe even
• https://github.com/paranext/ux/issues/149

[Sebastian-ubs]

TJs reply (in my words):

Settings of core and each extension are put into a single container “name” each and merged together into one flat array.

This name only virtually exists as a back reference to the extension that added a settings group. 

Currently a group has no unique identifier, there can be similarly named groups in each extension / core.


TODO: Decide as ux if we can use this or if the data structure has to change.

https://www.figma.com/board/WnpfPfYdiTX9GvLBX8YbTb/Platform-Settings?node-id=393-1647&t=BAco3Z5w3WKzbd2L-4

[Sebastian-ubs]

Hi @tjcouch-sil, after discussing with ux we ended up with wish for the following structure: https://www.figma.com/board/WnpfPfYdiTX9GvLBX8YbTb/Platform-Settings?node-id=416-2145&t=lwI8mWZAKgHNrGUx-4

Assuming that we can have (localized) Extension names or a fixed term name as clickable containers in the navigation sidebar.
I feel that we might get away without a general change of the settings structure (only added properties), but please let us know.

1. We want to throw together general settings of all core+bundled extensions+pt extensions (in the ui), each bringing their own settings group onto the page
2. We need a way to identify groups and specific settings
   a) for direct navigation
   b) to be able to pull them out and show them separately (e.g. account and language)
3. We need to define the order of settings groups inside a container; we need to define the order of containers inside project settings
4. We need to display some project settings in different containers (e.g. "project properties" and "user permissions"). If this requires them to be different extensions, that's fine to ux. Whatever technically and logically works better for dev. If that seems strange the settings structure should change to allow an extension/core to have multiple containers.
5. optional: Let an extension have no settings group and only settings
6. We need to a way to define that a setting would (not) show up in the settings ui

[Sebastian-ubs]

slightly updated comments (hope that helps for clarity)

"Settings", "Extensions" and "Projects" are only headlines in here

[merchako]

💡 It might be impossible for underlying Settings data model to always match what UX desires for their presentation in the Settings menu. Therefore, it might be expedient to introduce some sort of cheat to accomodate such mismatches, for example:

• Aliases, or
• Decouple the settings data from the display of them. Core and various extensions can create Settings modules, and these modules only get displayed if they're manually declared in a settings display file. (This is analogous to how components get used in .jsx or .svelte. or .mdx, but you could keep using object notation like JSON or YAML to define the settings).

Just an idea 😊

[Sebastian-ubs]

Thanks Alex. TJ specifically asked about requirements from ux, which might require changing the data model. Having a data driven ui and manually defining which settings end up in which place are two contrary (or at best supplementary) concepts.

After talking to Ian again, we ended up with the following
https://www.figma.com/board/WnpfPfYdiTX9GvLBX8YbTb/Platform-Settings?node-id=463-382&t=CY4wA5A5PJ3KnXfb-4
UX thinks thet best user experience will be with the following. Most likely this requires a change of the data model. In case it is a lot of effort option 1 or 2 could be reconsidered, but the wish would be to use 3.

[Sebastian-ubs]

Note that the last comment is about Paratext 10 presenting itself to the user as a unity, so that they do not (have to) think about it consisting out of Extensions. Therefore core + bundled extensions + PT10 extensions is to be presented as "this is Paratext" to them. To make them find things in an easy and intuitive way, we would not want to throw all settings from those on one big page, but have the ability to arrange them on logical pages, even when they are technically stored in / served by different parts.

Users of Paratext 10 would only see additional extensions they can get through the Marketplace as extensions, and so listing them separately makes sense.

For Platform however it might be fine to show all settings similar to where they are stored. But as it is unclear who the users of Platform would be (besides extension developers) it is not possible to cater for them.

[Sebastian-ubs]

@tjcouch-sil @jolierabideau are there any comments or concerns about the proposed settings hierarchy? As far as I understand this is not currently possible with the data model. The things I see missing is (for core, bundled and paratext extensions):

• id (I assume required for Add Direct Navigation to a Specific Setting #1251?)
• a free definition onto which page a group / individual setting would end up
• optional groups
• ui order
• "Do not show in ui"

Is that right? How are we gonna solve those requirements?

[lyonsil]

TJ and I talked about this one a bit. The right approach at this point is to probably change our schema for settings to be more like the schema we have for menus where platform can define some "root" starting points and identify locations in the hierarchy where extensions can contribute their own settings (which they can also mark as extensible for other extensions to add onto, if desired).

This will take a little redesign work compared to what is in the settings spec right now.

[Sebastian-ubs]

@lyonsil Will there be a new issue created for the settings hierarchy schema change, or will that be part of this story?

@jolierabideau I was able to recreate the design sidebar design in v0 close to what Ian created in Figma:
https://b_ng60yp8s2lf.v0.build/
You may try to copy the code (click "build with v0" below and "add to codebase" above)

Modifications from pure shadcn to mention:

• using an indent on the menu items (group) <SidebarGroupContent className="pl-4"> better be <SidebarGroupContent className="ps-4">
• using a fix top margin, because otherwise it would span over the search <Sidebar className="top-[73px]">

Probably search placeholder should rather be

Search app settings, extension settings and project settings

[Sebastian-ubs]

Just watching yesterday's dev sprint planning and @tjcouch-sil saying (regarding internet settings)

we can't put any non-setting into the settings dialog.

Which I would like to challenge. The possibility to add other stuff like controls in addition to settings will be helpful. E.g. we have thought about adding a link to the extension marketplace or even being able to enable/disable extensions from within there.
But regarding the internet settings that might be fine.

just don't tell ux

😄👍

[tjcouch-sil]

@Sebastian-ubs

The redesign and re-ordering needs its own issue. I think I have maybe seen an issue about this somewhere, but maybe it was a UX issue.

I will share more precisely the situation that led me to say "we can't put any non-setting into the settings dialog." Basically, I was saying there is not currently any place other than in the main process where settings are stored, and extensions can't freely put whatever they want into the settings dialog. There is no concept of storing settings elsewhere, and I'd argue it may not be wise to change that concept. However, others can listen in to the value of settings and do things based on that all they desire. We have not added a way for extensions to add their components into the settings dialog, but we are free to change that as we like. I have pictured it as providing one component for one setting up to this point, but I guess that could change. Of course, core can theoretically put whatever it wants into the settings dialog.

[Sebastian-ubs]

Thanks TJ, that sounds reasonable. I guess we are seeing a conflict here between technical limitation of "everything as an extension" vs. user experience of a user that considers Paratext a unity.
Another place where this conflict could appear is e.g. the Home/Open dialog and others may arise...
So we should ideally get together at a time and talk about the implications of this conflict, find 1 or few options for resolution and an easy decision tree when to apply which.
→ added a point to the UX+Dev discussion, but might require some thoughts of preparation

[Sebastian-ubs]

I've added

• Revise settings schema #1315

[jolierabideau]

@roopa0222 Here is the testing criteria!

• Searching
  • Right now it only searches the setting label, should hide the Card if there are no matching results
• Project web views should have an “Open project settings” menu item, when clicked should open a settings tab with no sidebar and only settings for that specific project.
• If you try to enter an invalid value, should show an error message below the input
• If you enter a valid value, should update the setting
• If you start the app, open the settings tab, stop the app, and reopen WITHOUT removing local storage, everything should load correctly. It will not remember what tab you were on, it will default back to the first extension settings tab

[merchako]

New mockups in response to PR #1354

• Design page PR#1354 Feedback combined (Figma)

which combines

• https://www.figma.com/design/zJWrApZ8AyPGxNHdndbkTz/Settings-Dialog-%23434?node-id=1056-899 and
• https://www.figma.com/design/zJWrApZ8AyPGxNHdndbkTz/Settings-Dialog-%23434?node-id=968-369

@ianhewubs @jolierabideau @Sebastian-ubs

[roopa0222]

Testing Repo Steps:

• Searching : Right now it only searches the setting label, should hide the Card if there are no matching results
  Need clarification if the 'Heading labels' are included in the search.
  Notice that the search only finds the field labels but not the headings

• Project web views should have an “Open project settings” menu item, when clicked should open a settings tab with no sidebar and only settings for that specific project.
  It is working as expected.

• If you try to enter an invalid value, should show an error message below the input
  Are there any known set of validation rules?
  I entered numbers in the Interface Language and it did not complain.
  

• If you enter a valid value, should update the setting
  It is working as expected. But not sure if all the fields have validations

• If you start the app, open the settings tab, stop the app, and reopen WITHOUT removing local storage, everything should load correctly. It will not remember what tab you were on, it will default back to the first extension settings tab.
  It is working as expected.

[jolierabideau]

@roopa0222 Thanks for testing!

Right now the search is only searching the label on individual settings, not the Card headers. There is a follow up issue to fix the settings search, so I didn't do too much work there.

The fields are validated based on that specific settings validation provided with the setting. It could be that the numbers are being read in as a string but the interface language validator accepts a string array, so I don't think it should have passed. This specific setting is being worked on by Tom, so I will mention it to him. Did you notice this on any others?

[roopa0222]

@jolierabideau , I tested that field as I know it can cause issues if the settings file is updated with an invalid language.
here is an issue related to that #1297

[tombogle]

With the changes I have done (separate PR for #1250: #1373), there is no text box for typing in a UI language. You can only pick from a set of valid options. So that won't be a problem.