Use swup for page navigation

[josevalim]

This will avoid reloading the page and only reloading the contents.

@angelikatyborska, if you have some time available, could you double check we don't have accessibility regressions? That would be very appreciated and I want to make sure this does not undo your previous contributions. :) Here is more information about the plugin we are using: https://swup.js.org/plugins/a11y-plugin/

Note that we are currently redrawing the sidebar, because the code that checks if a sidebar item is open or not is done while rendering. However, this still feels very snappy, so we are probably fine going down this route.

[angelikatyborska]

I'll take a look in the next 24h 🙂 thanks for the ping

[josevalim]

Thank you, @angelikatyborska ! I found bugs, I will let you know once they are addressed first!

[josevalim]

@angelikatyborska they have all been fixed. It should be ready for evaluation :)

[josevalim]

Oh @angelikatyborska, for you to give it a try, you will need this:

$ mix build
$ python3 -m http.server 8000

Or erl -S httpd in recent Erlang versions.

And then you can access localhost:8000/doc/index.html

If you need to do changes, you can run mix build again in a separate terminal, but remember to disable caching in your browser.

[angelikatyborska]

I did some manual accessibility testing on this PR and found two issues. One moderate that's likely caused by this PR, and one very serious that's likely unrelated to this PR, but I feel compelled to mention it because of the high severity.

Overall, this library with the a11y extension seems to behave very nicely and gives adequate feedback to screen reader users about what happened by reading out the h1 of the new page content or the specific h2/h3/... if navigated to a specific section on a page. The experience could be improved further if those links to "view source" and "link to this function" were semantically outside of the heading. Currently if you navigate to e.g. "API Reference", the announcement says "Navigated to view source API reference". It would require a bit of a CSS rewrite.

Bugs

I recorded videos to explain them, let me know if you need further help figuring out how to fix them. I didn't have the time to also do that today 😅

Moderate severity: keyboard navigation of tabs breaks after navigating to a new page

Explanation video: https://www.loom.com/share/f83a0fcf6b1f486daf8fffede76f6448?sid=f928f94b-61ef-4d06-9650-1750875f9144

High severity: search bar traps focus, keyboard navigation of the page is impossible

Explanation video: https://www.loom.com/share/d028fed02eba49668306fb4454461c6f?sid=2f310557-a113-4bb4-95ac-1d9a94453206

[josevalim]

Fantastic. I could reproduce those two outside of this PR, so I will merge this and work on these two issues next!

[josevalim]

💚 💙 💜 💛 ❤️

[josevalim]

and thank you @angelikatyborska!!!!

[angelikatyborska]

I'm always happy to help with web accessibility of Elixir projects 🙂

[josevalim]

@angelikatyborska the high severity one has been addressed. :)

[josevalim]

I misspoke. There were three reports and the first video applies to this PR. I will fix it as well.

[josevalim]

All fixed. @angelikatyborska the sidebar tabs is a funny one. We were initializing the event handler multiple times, which means that, the first time the page was loaded, clicking the arrow would move one tab one. Once you navigated to a separate page, it would register again, so clicking the arrow would move it twice, giving the impression it would go back. The third time, would move three, so it appeared like not moving at all. And the fourth time would "fix it". :D