In light of the question of how URLs should be percent-encoded (#42), I think there is a more pressing underlying issue.

There is confusion about how Url.Builder and Url.Parser methods work, since the documentation on percentEncode makes it seem that functions like absolute, relative, and crossOrigin will also do percent-encoding on the paths, as evidenced by the top comment in #25.

To address the misunderstanding of what gets percent-encoded by those functions and how to achieve the desired behavior, we can change the documentation for percentEncode from

Use Url.Builder instead! Functions like absolute, relative, and crossOrigin already do this automatically! percentEncode is only available so that extremely custom cases are possible, if needed.

to something like

Use Url.Builder instead! Functions like absolute, relative, and crossOrigin already encode query parameters automatically! percentEncode is only available so that extremely custom cases are possible, if needed.

Note that these functions do not percent-encode path components, because not everyone needs the same encoding. If you need to do that, you need to call this function on each path, for example Url.Builder.absolute (List.map percentEncode ["encode me"]) [] to get /encode%20me.

Similarly, the documentation for percentDecode can be changed from

Use Url.Parser instead! It will decode query parameters appropriately already! percentDecode is only available so that extremely custom cases are possible, if needed.

to

Use Url.Parser instead! It will decode query parameters appropriately already! percentDecode is only available so that extremely custom cases are possible, if needed.

Note that Url.Parser does not percent-decode path components, because because not everyone needs the same encoding. If you need to do that, you can create a custom Url.Parser with custom "STRING" Url.percentDecode.