Add support for query params and fragment to Route.toLink

[dbj]

Proposal: Add support for query params and fragment to Route.toLink.

Recently I needed a way to add a fragment to the Route URL generated by Route.toLink (via Route.link). In order to do this, I had to write a custom toLink function. My solution was to pass in a record:

{ query: Dict String (List String)
, fragment : Maybe String
}

which used the PageUrl type as a example.

I think it would make sense to add the ability to add query params and fragment to the native implementation of toLink as query params and fragments are formal parts of the URL and should be easily leveraged in the framework.

This issue is to start the conversation regarding the best interface for such a feature-add.

[dbj]

Dillon did bring up in the Elm Slack forum that perhaps a builder pattern or other pattern might be a better, permanent approach (see https://elmlang.slack.com/archives/CNSNETV37/p1717041342001139?thread_ts=1717006053.081689&cid=CNSNETV37).

[dbj]

In thinking about the best interface, personally, I don't think the Builder pattern lends itself to toLink because toLink is intended to take a Route that has already been defined, and then return an anchor tag to be rendered in a view. Its a "quick" function with a very specific job with not a lot of customization or variation. The Builder pattern emphasizes customization and variation, and toLink is not about that.

Another approach would be to just accept a string for the query. There is already a query builder in elm/url, so no need to recreate the wheel there, so we could recommend devs use the query builder to build the query string they pass in, but then we'd need to be sure to validate the query string inside toLink because there is nothing to ensure the query builder was used.

A third approach could be to look to the PageUrl type in elm-pages, or better, create a more specialized query and fragment type patterned after PageUrl called UrlOptions:

type alias UrlOptions = {
    query : Dict String (List String)
    fragment : Maybe String
}

We could add to the PageUrl module a urlOptionsToString function for the UrlOptions type:

url_options = {
    query = query_dict
    fragment = Nothing
}
url_options_string = PageUrl.urlOptionsToString url_options

urlOptionsToString would be guaranteed to return a valid options string that includes the query and/or fragment represented in the UrlOptions type.

We could expand toLink to take a Maybe UrlOptions in the parameter list:

toLink : (List (Html.Attribute msg) -> abc) -> Maybe UrlOptions -> Route -> abc
toLink toAnchorTag urlOptions route =
    let
        url_options_string = Maybe.map (\url_options ->
            PageUrl.urlOptionsToString url_options
        ) urlOptions
        |> Maybe.withDefault ""
    in
    toAnchorTag
        [ Html.Attributes.href <| (toString route) ++ url_options_string
        , Html.Attributes.attribute "elm-pages:prefetch" ""
        ]

I think this approach might be most consistent with elm-pages, avoids the perhaps unnecessary complexity of the Builder pattern, and still keeps the toLink call "quick" and easy to reason about using - when a dev doesn't need to worry about url options, just pass in Nothing.

And finally, with this third approach, PageUrl could also provide a UrlOptions builder patterned after the query builder in elm/url so as to make it easy to build out the UrlOptions Dict.