Make HTML functions return Doc, have extra Elt.x functions that return Elt

[Tarmil]

With the hindsight from using UI in many applications, I've come to the conclusion that:

• The vast majority of use cases for DOM elements do not make any use of Elt-specific APIs like .Dom, .OnEvent, .AppendDoc, etc and could just as well have type Doc.

• There are many situations where we need to upcast from Elt to Doc, which is more verbose than necessary.

  Examples:

  • Branches with different types:

    if someCondition then
        Doc.Empty
    else
        span [] [text "test"] :> Doc

  • Higher-order functions:

    let mkList (count: int) (generate: int -> Doc) =
        ul [] [for i in 1..count do yield li [] [generate i]]
    
    let elt = mkList 10 (fun i -> span [] [text (string i)] :> Doc)

  • Lists that the compiler would otherwise mistakenly think are heterogeneous:

    [
        Doc.Empty
        span [] [text "haha"] :> Doc
    ]

  • yield (this one will apparently be fixed in F# 4.5):

    div [] [
        yield span [] [text "test"] :> Doc
        if someCondition then
            yield a [attr.href "/"] [text "test"] :> Doc
    ]

I therefore propose that:

• Functions such as div, span, etc from the WebSharper.UI.Html module should return type Doc instead of Elt.
• A new module WebSharper.UI.Html.Elt should be added, with these same functions returning Elt.

Obviously this is a breaking change, but I think it's a worthwile one that will both make learning easier and real-life code more readable.

Note that this only concerns the F# API; C# performs enough automatic upcasting that this is not problematic there.

[cata]

@Tarmil I'm all for it. I can't think of one single case where we use Elt-specific APIs in our code. on the other hand, upcasts from Elt to Doc are pervasive.

[Tarmil]

Change applied in 6be098a.