Url (de)serialization: Cover and document all edge cases

Situation: Links and Urls are needlessly parsed and serialized. The serialization format is not declaratively stated. Filters and Links don't fit well in a single type.

Desires:

[ ] The relation between Link, State and Url should be stated in a declarative, in-code fashion.
[x] The Link type and the potential Filter type should embody clear use patterns of the Ui state.
[ ] The encoders and parsers should be either more declarative or have full, declarative-style test coverage.
[x] Clear expressions for links and filters that are just used to draw contingent Ui.
[ ] To defunc the Ui type (-> #16), \[]->... in Filter should be replaced by a defunctionalised constructor (sth. like Predicate)
[x] No more redundant parsing and serialization steps
[ ] Settle for a minimal escaping scheme with "+" for %20 (follow elm-app-url)
[ ] Check edge cases on different browsers/devices
[ ] Decide at which point to sanitize Urls -> #50

Related issues in order of decreasing relevance:

Questions:

Can we just use elm-app-url which happens to treat "a=" as "a" but "=" as (""="")? How does it treat "a=b=c" which is relevant for making filters selectors? Is it a good basis for the link encoder and queryer and for the url*state parser? A: No.
Do we need an Url sanitizer?

Api and Invariants

Link.href 
   : Link -> String

hrefs are always minimal, i.e. they represent only the intended transition from the current state to the new one.
Relative operations are encoded in protected assignments. Custom assignments are escaped accordingly.

Link.applyUrl 
   : { makeAbsolute : Bool } -> State -> Url -> State

A new path and fragment replaces the old path and fragment. New flags append to the existing ones. New assignments replace the existing ones.
Relative operations are made absolute if makeAbsolute is True:
- Toggle becomes turn on;
- Bounce { there, here } becomes GoTo there
Imply any flag or path that needs to be present such that the intended path and fragment is rendered.

Link.isActive 
   : State -> Link -> Bool

Link.getCurrentData
    : State -> Link -> Maybe Data

When to use links

The Url is a state shared by all interactive elements in a tab. It is very easy to manually edit, to share and to reproduce, but its utility diminishes when the Url gets too long:

The user potentially wants to share the state
The state can be reasonably serialized and edited
The serial form can be kept short
The total number of decisions in a Url is kept within the single digits
The pattern is neither too specific nor too general
The pattern is well-established and/or well-loved in existing applications
The pattern composes well with regions and nested occlusions
The pattern is not parallel to the model, i.e. the model has no variable that mirrors the pattern state, but the model may choose to track it, e.g. to store a per-user list of "recent items" or to (pre)fetch a subset of the model according to such a list.

Sample patterns

Token

token : { flag, label } -> ((String, Ui), (String, Ui))
token { flag, label } =
    let
        inner = (flag, toggle { flag, label })
    in
    ( filter ( flag )
        ( \flags -> if List.member flag then inner else [] )
    , filter ( flag )
        ( \flags -> if List.member flag then[] else inner )
    )

Set

set = 
    [ { flag = "a", label = "A" }
    , { flag = "b", label = "B" }
    , { flag = "c", label = "C" }
    ]

(activeTokenList, inactiveTokenList) =
    List.map token set
        |> List.unzip
        |> Tuple.mapBoth (Html.ol []) (Html.ol [])

view =  
    activeTokenList ++ Html.singleton [ Html.text "⇋" ] ++ inactiveTokenList

Implement in `Html`:

wrapper	Link	Filter	Toggle
	`"a#b"` `{ bounce=""}`	`List "?category="`	`"?flag"`
	`"a#b"` `{ bounce="c#d" }`	`List "?category=subcat="`	`"?parameter=value"`
Html tag	a`aria-current="page"` `attr` label	label ++ input `current` `type_ "search"` `value` `attr`	a `role "switch"` `aria-checked..` `attr` label
Contingent	`Ui`	`List String -> Ui`	`( Ui, Ui )`
Attribute	href `"a#b?bounce=c%23d"`	onInput `(Filtered [categories])`	href `"?flag&toggle=flag"`
Style	isInline	isInline	isInline

Ui.Wrapper
`Stateful (State -> { label : html, isInline : Bool, contingent : Ui ))`

At Ui.view, the given layout unwraps the Link/Filter/Toggle wrapper into a Stateful; and then the html part is put smewhere according to .isInline, and the Ui part of it is rendered at the current region. Both the Ui and the label are checked for emptiness (like in the current implementation) and wrapped in layout.removed etc.

Advantages:

Cohesion between Link/Filter/Toggle constructor and its complete view
No more coupling across modules -- except everything that knows Url.
Ui is completely stateless

Disadvantages:

No more restriction on Ui.Stateful
More repetition in layout modules (elm-ui, elm-css, elm-widget)

Question: Where should the Url and href management live? (a) Completely within Restrictive; we'd need a separate State or Msg module to provide defunc primitives for building transitions, including for the onInput Msg case (b) Completely within Ui, i.e. Ui would provide these primitives (c) In Html, i.e. Apps and Uis would remain stateless, and state would be routed through the Layout exclusively.

Answer: Since Restrictive.AppState owns the Url, we want to cram all parsing and serializing functions into that module. Otoh, Html already covers all link types, and link types may not generalize across layout types... which would favor (c)... but then, where to place the codecs?

Question: Where should the Link and Filter types live?

href : Link -> Attribute (Msg msg)
applyFilter : Filter -> Attribute (Msg msg)

ToDo:

[x] Implement the Stateful constructor of Ui.Wrapper
[x] Replace the state parameter at Ui.view by a switch in Layout such that there is a stateless layout and one where the state is applied, namely to any Stateful wrapper.
[x] Apply the state to the layout at Restrictive.mapDocument
[x] Implement the Html link creation functions as outlined in the table
[x] Wire up the state comparison mechanisms
[x] Wire up the "link-less" application logic
- [x] Msg (apply relative changes)
- [x] LinkClicked (apply relative changes)
- [x] init (replace Url)
- [x] UrlChanged (replace Url)

Question: After 2 refactorings and lots of little edge cases yet to cover, I wonder which approach is more future-proof: (a) (Re)Introduce a declarative builder/codec with opaque types. Less general than elm-url-codec and with some features features that elm-app-url is missing. Perhaps such a library exists already. (b) Use tests, preferably directly in the comments, instead of types, to "describe" the functionality and cover all edge cases

upsiflu / less-ui