Interactive configuration builder - Setup beautifiers, languages, and options

[stevenzeck]

Poll: Which do you prefer https://clangformat.com/ or http://csscomb.com/config ?

---

Must Haves

• [ ] Display checkbox list of all languages that Unibeautify supports, serves as step 1
• [ ] Generate unique list of options based on all of the languages the user selects
• [ ] Loop through all options, displaying a page for each one
  • [ ] Display box for each value for the option, including a code sample, along with a "don't use this option"
  • [ ] Allow the user to select the value for that option
  • [ ] Show a page for selecting beautifiers? I kind of feel we need to do this, as some beautifiers you don't have the same amount of control over
• [ ] Generate yaml and json text based on the languages and options the user selected
  • [ ] Ensure options under each language are supported by the language so we don't bloat the file

Nice to Have

• [ ] Previous and Next button text should be the name of the page the user is going to next
• [ ] Allow users to download the file directly from the browser

I found CSS Comb's build config flow interesting: http://csscomb.com/config.

[stevenzeck]

@Glavin001 How will Setup Beautifiers work exactly? Are we going to have the option to select which beautifiers to install versus putting them all in the editor package.json?

[Glavin001]

I would like to present the user with the supported options for each beautifier. If the user only wants to use a subset of the possible configuration options, then there may be beautifiers which are unnecessary to achieve the desired beautified result and can therefore be removed. Consider the Options table for JavaScript language: https://unibeautify.com/docs/language-javascript.html#options

I think an interactive tool similar to CSSComb's may allow users to choose "I don't care" for "Choose the code sample you like more:" which would allow us to narrow down which beautifiers we actually need to apply.

Thoughts?

[stevenzeck]

OK, so this has nothing to do with the installation of beautifiers themselves?

What would be the difference between Setup Beautifiers and Configuration Beautifiers?

[Glavin001]

I think the original intent of Setup Beautifiers was for resolving error messages like "Could not find XYZ program". The configuration part of the assistant being what we are describing above.

[stevenzeck]

I've started working on this. I'll need some help getting the options pulled in from where ever the source ends up being, and how to best go about "saving" each selected option as they go through the wizard.

Bootswatch has cards that are perfect for putting code samples in, although I need to figure out how to make them all the same width and height since samples will take up different amounts of whitespace.

[stevenzeck]

How I'm approaching it (everything mentioned is under src/pages/setup) @Glavin001 would like your input on this design and where you would make changes since you know React a lot more than I do.

1. index.tsx serves as the welcome/starting page for configuration. Probably will have a drop-down for the language users want to configure, which will be passed to the "Wizard" component.

2. The Wizard component creates the base UI for the wizard (buttons for steps, how many steps there are, etc.). The states I have keeping track here are:

• preStepName: The name of the previous step (in these cases the name of the option), which will be displayed as text in the PREV button
• nexStepName: The name of the next step (in these cases the name of the option), which will be displayed as text in the NEXT button
• stepName: The current step name, to display in the header
• language: The language you are configuring

The first three would change when the user switches which step they are on. The wizard will render the base UI, along with OptionButton components.

3. The OptionButton component is each card. The props that are passed in are "name" for the value of the option in the header and "code" for the sample code in the body. The language from the Index and Wizard is passed for highlightjs to syntax highlight.

https://github.com/szeck87/assistant/tree/options-wizard

[Glavin001]

I was thinking:

• Users selects 1 or more languages from list of language checkboxes
• Custom configuration plan is created
• For each option show example
  • Include "I don't care" option so we know which option we can ignore. This allows use to disable beautifiers which support options the user does not care about
  • Use the previous configuration + this new option to generate the example, so it is as personalized for the user as possible (not simply hardcoded option examples)
• Generate configuration file
  • JSON and YAML formats
  • For all languages
  • Only enable beautifiers which are required based on options selected

[stevenzeck]

Holding off further until data fetching and beautifying is resolved.

[Glavin001]

Holding off further until data fetching and beautifying is resolved.

Sounds like my kind of thing 😄 . Reassigning.

[Glavin001]

@szeck87 Do you have a branch you could create as a PR and I will take it over?

[stevenzeck]

https://github.com/szeck87/assistant/tree/options-wizard?files=1

I was mostly waiting to decide what to do with the API, whether to have one that there playground and assistant is or one of each.

[Glavin001]

I think I'll build a reusable API for these public sites. I am still working out how this should function and also be funded.. I want to use Docker and haven't found a free way to run a Docker server 😜 .

[stevenzeck]

https://clangformat.com/

[Glavin001]

@szeck87 Wow that looks great, too!

Which do you prefer https://clangformat.com/ or http://csscomb.com/config ?

[Glavin001]

Holding off further until data fetching and beautifying is resolved.

@szeck87 New Playground API has been created: https://github.com/Unibeautify/playground/pull/26 It includes support for non-Node.js beautifiers, such as PHP-CS-Fixer. See https://ntd6xp2n56.execute-api.us-east-1.amazonaws.com/dev/playground/support

[Glavin001]

@szeck87 you can pass stdin like this: https://github.com/Unibeautify/unibeautify/blob/461d80e005ef838e83c5d948bd5b7554681d18e7/test/DependencyManager/ExecutableDependency.spec.ts#L161-L168

[stevenzeck]

Which do you prefer https://clangformat.com/ or http://csscomb.com/config ?

I like the idea of having the options in a list so you can easily go back to one without going through step buttons. And also a description of what the values mean, but that would require an interface change in Unibeautify. However it lacks a real builder where you can select something and are able to download the config file itself.

I think a hybrid would look/function well. First and last steps are always "Select Languages" and "Finish" or something, where the latter would have the config file available for download. Once the languages are selected, the left pane would list out all of the options based on them. The rest would look something like https://github.com/Unibeautify/assistant/issues/11#issuecomment-381301455. I don't know if the code toggle like clang-format has there would work all of the time, depending on how many values are there for an option. It certainly looks better than the boxes from csscomb and ours.

[Glavin001]

@szeck87 's progress: https://github.com/unibeautify/assistant/tree/options-wizard

[Glavin001]

From @szeck87 :

1. List supported languages with checkboxes
2. Build options based on languages selected (upon clicking next button I assume)
3. Select languages, each option, and a final page would be in the left nav
4. Each option page would have a small sample code set to show what it looks like csscomb and clangformat put together

[Glavin001]

@szeck87 Here's what I have so far:

Now we need real examples for each of the languages.

I think you suggested earlier putting all of the examples into a separate and central repository and then including it into Website and Assistant? Would you be able to work on that and finish off this PR? 😃

[Glavin001]

@szeck87 : Thoughts on adding analytics to the process? We could track how long it takes a user to complete X number of options choices and then calculate an average. Then later we could say "you have Y steps with X options to choose, it usually takes someone Z minutes to complete"

[Glavin001]

We could detect whether the beautified samples are actually unique. If they are not, we could add a button to say "Report a problem" or something, since the samples do not demonstrate how the option will change the code.

[stevenzeck]

Yea I like both of those ideas. Give users the ability to report that there are issues with the steps, and at the same time we can track. Can we track how much time a user spends on a specific option?

I also think we don't need the Add/Edit example buttons here. Maybe a link in the metadata that says More Info and links to the unibeautify.com page for that option, where it has the buttons?

[Glavin001]

Can we track how much time a user spends on a specific option?

We can track anything we can measure (in milliseconds) and send to Google Analytics with https://developers.google.com/analytics/devguides/collection/gtagjs/user-timings

So we could track a step page, such as 10. Align Assignments which has 4 languages and they spend X milliseconds on it. 👍

I also think we don't need the Add/Edit example buttons here. Maybe a link in the metadata that says More Info and links to the unibeautify.com page for that option, where it has the buttons?

I really want to encourage users via the website and now here in the assistant to contribute. If the sample does not demonstrate properly, change it! If there is no sample, add one! I want to leverage the power of the open-source community as much as possible.

[Glavin001]

While playing around with the assistant I found a problem.

I reproduced it in the Playground:

• Bad
• Good

Currently all beautifiers are enabled in some arbitrary order. We need to provide tools so users know cases like this "If you care about option X, then Prettier respects it and Pretty Diff messes it up. You want Prettier to be before Pretty Diff." 🤔

[stevenzeck]

Currently all beautifiers are enabled in some arbitrary order. We need to provide tools so users know cases like this "If you care about option X, then Prettier respects it and Pretty Diff messes it up. You want Prettier to be before Pretty Diff."

Sort of goes back to one of the Must Haves: "Show a page for selecting beautifiers? I kind of feel we need to do this, as some beautifiers you don't have the same amount of control over"

Beautifiers like Prettier don't support many options and even override what other beautifiers do since it's opinionated. How does the pipeline work exactly? Does it go through one beautifier first, then the next, and so on? If Prettier is always the last, very little of how you configure Unibeautify might be used.

[Glavin001]

How does the pipeline work exactly? Does it go through one beautifier first, then the next, and so on?

Yes, exactly. beautifiers: ["A", "B", "C"] goes in order of the items in the array. This works great if you know what you are doing. Not great for beginners, who may be very surprised when a beautifier wipes out their formatting from previous beautifier.

If Prettier is always the last, very little of how you configure Unibeautify might be used.

Very true.

---

One idea is to order by importance. For example, if you have options A, B, C configured and each are supported by a different beautifier, you could apply the beautifiers in reverse order -- the most important being last. For example, this could mean Prettier (opinionated) first and ESLint (configurable) second, which is what https://github.com/prettier/prettier-eslint does. 🤔