Version picker

[jonaskuske]

I built the version picker to choose between the different available builds, feedback welcome!
Preview link: https://deploy-preview-90--watercss.netlify.com/dist/docs/

A few notes:

• Since water.css v2 with CSS variables is not officially published yet, the legacy non-standalone versions don't work, as they reference the CDN. (Also, the README instructions are wrong as v2 is merged but not published...)
• Docs files are currently located in docs/ and then compiled to dist/docs. I don't know what makes most sense here, but the Netlify config needs to be adjusted one way or another.
• File size information is currently hard-coded into the JS, but we should aim to integrate this with our build step so file sizes on the docs page are automatically updated with every re-build. But I'd say that's a future concern and no merge-blocker, unlike the other two points.
• You can specify the initial selected version via URL parameters theme=dark|light, standalone and legacy, e.g. index.html?theme=light&standalone which can be handy when linking to it from the docs.

fix #27, fix #88, fix #84, fix #89

[kylejrp]

Great work @jonaskuske! Like I've mentioned before, I love the version picker and how easy it makes installation.

I've requested a few changes and added some feedback in my review.

Since water.css v2 with CSS variables is not officially published yet, the legacy non-standalone versions don't work, as they reference the CDN. (Also, the README instructions are wrong as v2 is merged but not published...)

Yup, we'll need v2 published to NPM before merging. cc @kognise

Docs files are currently located in docs/ and then compiled to dist/docs. I don't know what makes most sense here, but the Netlify config needs to be adjusted one way or another.

That's okay, we can always move it later. Again, cc @kognise on the Netlify config.

File size information is currently hard-coded into the JS, but we should aim to integrate this with our build step so file sizes on the docs page are automatically updated with every re-build. But I'd say that's a future concern and no merge-blocker, unlike the other two points.

I agree, great solution for now and we can integrate this later into our build tools.

You can specify the initial selected version via URL parameters theme=dark|light, standalone and legacy, e.g. index.html?theme=light&standalone which can be handy when linking to it from the docs.

Nice bonus feature! Great idea.

[jonaskuske]

Two notes:

• When opened in legacy browsers, the legacy option will be defaulted to true in the initial version picker settings, so that the site does not look broken on launch (only once you actively disable the legacy option)
• Since the site loads a copy of water.css already before the JS could determine the selected version (otherwise you get a FOUC), the initially-loaded copy and the one that's used once the version picker is ready can be different in very rare cases: when you use the URL parameters to tell the picker to start up with a standalone version instead of the default one, and the loaded standalone version happens to differ from the active theme the initially-loaded version was showing.
  We could avoid this by making the whole page wait with showing anything until all the JS is loaded, but I don't think that this small edge case justifies the additional loading time.

[jonaskuske]

Okay @kylejrp @kognise , anything else preventing this from getting merged?

I've just updated the build step so the dist/docs directory contains its own copy of the compiled water.css stylesheets. So the docs directory is now self-contained and should not cause any problems with broken links when you update the Netlify config to use dist/docs/ as the base of the website.

I think these are the next steps:

1. Publish current water.css. That's long overdue anyhow, the README currently contains false instructions because v2 was merged without publishing.
2. Update Netlify config so dist/docs is the base URI for the documentation website?
3. Merge and be done with it. ✔

[kylejrp]

I've emailed @kognise and would love to get this merged. We just need the netlify configuration up to date.

Once we hear back from @kognise, we can get the branch up to date and resolve any merge conflicts. Then we can get @jonaskuske's hard work finally into master.

Thanks so much for your patience.

[kylejrp]

Hey @kognise, any chance you can still update the Netlify configuration so that the publish directory is dist/docs? Then we can merge this awesome contribution from @jonaskuske!

[jonaskuske]

Mentioned over in the Next Steps issue (#187) that we might want to re-visit and potentially streamline the version/naming strategy.

That's because basically all relevant browsers support (prefers-color-scheme) now, so the Dark/Light selection (without "Enfore theme") is really just specifying the fallback look for users in some older browsers. I don't think the current UI is communicating this clearly enough, so devs coming to the docs site might select Dark/Light and wonder why almost nothing changes.

But updating the UI of the docs site is no breaking change of course, so if we keep all file names the way they are we can just merge this and improve the UI later – in that case I'd create a separate issue.

cc @kognise @kylejrp

[kognise]

Sounds awesome - if we end up doing what I outlined in my last reply to #187 it might be better to make the ui changes in a separate pull request.

[kognise]

I'm going to close this pr because I've already manually merged it into the two branch - thank you for your effort getting this working!