Documentation updatates

[AngelMunoz]

As mentioned in #53 I'd like to revisit some of the documentation and add more information that may not be obvious to new users or folks not entirely in the loop of blazor things Feedback is welcome!

[albertwoo]

@AngelMunoz thanks for the contribute first.

Some concern for the DOM document, I think it is too complex. Before I just want to explain the Fun Blazor Core, the DSL. Other stuff, like html.inject, adaptive, reactive, elmish are advanced features and very opionated, someone likes and someone hates.

And currently, the template like fun-blazor are just using regular csharp style, not using any of the advanced features. So it may freak people out. I would recommend to move your explanation for those advanced features to related section, and maybe add some doc ref in the DOM doc.

[AngelMunoz]

The reason I went all in with the DOM document is because I feel it is a natural progression from someone's code for example:

1. Start writing html and handle a few things here and there
2. Start adding control flow/multiple items
3. Start handling state or look for state management solutions

I think the Technical "Core" of the Fun.Blazor project is indeed a small layer on top of blazor, but I think as a "Framework" these concepts in the DOM document are "Core" the framework at user level.

If users are able to understand these few pieces and how they match, then they can start figuring out the rest.

While there are advanced use cases for them, I don't think they are by default advanced.

I wanted to reserve the "Advanced" area for things like Blazor Interop (like the document I moved there from the DOM), JavaScript Interop, AutoInteractive Rendering mode (the client, server plus service sharing) and other things thar are not kind of the "day to day" things everything else it can have its own section but I don't think they should be categorized as "advanced" at all.

Thoughts there ^?

Another thinking I have is that: Too few information I think it also hurts because it just raises questions about the missing pieces.

Other stuff, like html.inject, adaptive, reactive, elmish are advanced features and very opionated, someone likes and someone hates.

I agree that they may be opinionated but shouldn't the framework kind of enforce a little bit how it wants to be used?

I think adaptive data is the one you'd like to push as the default right?

The other solutions I tried to write them a little bit more of "it is an option"

[AngelMunoz]

I moved the dynamic content to the section "Interactive Nodes" as it is a similar wording used by the microsoft docs to distinguish between content that reacts to user input

[albertwoo]

For any element or component which has child content, we can just use for loop like:

div {
    for i in 1..5 do
        p { $"p {i}" }
}

[AngelMunoz]

Ideally we still want to keep the key attribute right?

Also, should I mention the yield! keyword for multiple items? e.g.

div {
    h1 { "title" }
    ul {
        fragment  { yield! listOfLiNotdes }
    }
    p { "Text" }
}

[albertwoo]

This point is not very clear to me.

Regarding for performance, both function or component style requires diffing. Because function style node is just a delegate which is waiting to be called by its parent.

For component directly inherit from FunComponent or ComponentBase, dom event will trigger rerender and the whole content of the component will be used to computate the diff. But if we use FunBlazorComponent which the event trigger rerender is disabled by default, so it can be used together with adaptive or observable and only specific area of the component's content will need to be used to computate for diff when data is changed:

type Demo() =
    inherit FunBlazorComponent()

    let data = cval 0

    override _.Render() = fragment {
        p { "xxxx" }
        adaptiview() { 
            let! data = data
            // only this part will need to be used for computate for diff when data is changed
            p { $"x = {data}" } 
        } 
        button {
            onclick (fun _ -> data.Publish((+) 1))
            "Increase"
        }
    }

For

[AngelMunoz]

Regarding for performance, both function or component style requires diffing. Because function style node is just a delegate which is waiting to be called by its parent.

What I tried to mean here is that (at least I think, let me know if I'm wrong here) that a bigger tree diff is more costly than diffing just what the adaptiview has to diff

but I'll make the distinction between FunComponent and FunBlazorComponent for those cases.

But if we use FunBlazorComponent which the event trigger rerender is disabled by default, so it can be used together with adaptive or observable and only specific area of the component's content will need to be used to computate for diff when data is changed:

Ah yes that's what I wanted to say, I missed the FunBlazorComponent entirely, I will change this section, thanks!

[albertwoo]

@AngelMunoz

I think the Technical "Core" of the Fun.Blazor project is indeed a small layer on top of blazor, but I think as a "Framework" these concepts in the DOM document are "Core" the framework at user level.

At the begining, I actually put all the opinionated stuff at first and push adaptiview and hook, at some point I changed my preference when I use Fun.Blazor for my own projects like my blog site (I only use SSR + htmx now). So for myself, my opinion is not stable.

And framework is too big for me to position Fun.Blazor, so at some point of time, I re-organized the docs and put DSL as the most important one, and other stuff as advanced toolsets. Because I do not want to fight the blazor official way, that is also the reason I updated the templates to use the component style and use blazor's default features as much as possible.

But maybe you are right, because maybe for many fsharp developers, they do not care how official blazor works, they just want to use familiar fsharp sytax to compose some dom together and hook up some dynamic data, and that is it. So maybe we should provide templates in more fsharp style and more opionionated way.

[AngelMunoz]

And framework is too big for me to position Fun.Blazor

I think when adaptiviews/html.inject/hooks and other features specific to Fun.Blazor are used they're more than just "libraries" or "tools" in my personal opinion using them all together really takes Fun.Blazor at a Framework level just like a Giraffe is positioned in ASP.NET, sure they are technically libraries that build on tip of existing frameworks but they add that extra glue/ease of use that make it its own thing.

Because I do not want to fight the blazor official way,

I think this is a very strong point for Fun.Blazor and it should keep being Blazor friendly in all aspects possible. because F# users "may not need this until they do" but when they do it is extremely good to have it around.

I think your last point has value, and I agree, most of the time F# developers just want to get things done so, having an F# friendly/oriented guide more than "how the official blazor way works" provides more value than not having it or having it buried in other places in the documentation

I use Fun.Blazor for my own projects like my blog site (I only use SSR + htmx now)

That's why I want to keep a list of existing libraries that are part of the Fun.Blazor family for more people may bring a lot of value to use this combination of tools, just like other ways to use it bring value to other set of developers it is just matter of being able to communicate that in the docs which I'll try my best to add what I can.

[albertwoo]

Thanks for the hard work, I will merge it now.