clean up docs

docs/make.jl

@@ -10,14 +10,21 @@ makedocs(
     authors="Simon Danisch and other contributors",
     pages=[
         "Home" => "index.md",
-        "Styling" => "styling.md",
-        "Layouting" => "layouting.md",
-        "Widgets" => "widgets.md",
-        "Animation" => "animation.md",
-        "Plotting" => "plotting.md",
+        "Components" => [
+            "Styling" => "styling.md",
+            "Components" => "components.md",
+            "Layouting" => "layouting.md",
+            "Widgets" => "widgets.md",
+            "Interactions" => "interactions.md",
+        ],
+        "Examples" => [
+            "Plotting" => "plotting.md",
+            "Wrapping JS libraries" => "javascript-libraries.md",
+            "Assets" => "assets.md",
+            "Extending" => "extending.md",
+        ],
         "Deployment" => "deployment.md",
-        "Assets" => "assets.md",
-        "Extending" => "extending.md",
+        "Static Sites" => "static.md",
         "Api" => "api.md",
     ]
 )

docs/src/api.md

@@ -2,6 +2,7 @@
 
 ## Public Functions
 
+
 ```@autodocs
 Modules = [JSServe]
 Order   = [:module, :constant, :type, :function, :macro]

docs/src/assets.md

@@ -25,7 +25,7 @@ DOM.img(src=some_file)
 # This will also resolve to a valid URL and load jsmodule as an es6 module
 DOM.sript(src=jsmodule, type="module")
 
-# Assets also work with online sources, which is great for online dependencies!
+# Assets also work with online sources.
 # Usage is exactly the same as when using local files
 THREE = ES6Module("https://unpkg.com/three@0.136.0/build/three.js")
 # Also offer an easy way to use packages from a CDN (currently esm.sh):

docs/src/components.md

@@ -0,0 +1,58 @@
+# Components
+
+Components in JSServe are meant to be re-usable, easily shareable types and functions to create complex JSServe Apps.
+We invite everyone to share their Components by turning them into a Julia library.
+
+There are two ways of defining components in JSServe:
+
+1. Write a function which returns `DOM` objects
+2. Overload `jsrender` for a type
+
+The first is a very lightweight form of defining reusable components, which should be preferred if possible.
+
+But, for e.g. widgets the second form is unavoidable, since you will want to return a type that the user can register interactions with.
+Also, the second form is great for integrating existing types into JSServe like plot objects.
+How to do the latter for Plotly is described in [Plotting](@ref).
+
+Let's start with the simple function based components that reuses existing JSServe components:
+
+```@setup 1
+using JSServe
+JSServe.Page()
+```
+
+```@example 1
+using Dates
+function CurrentMonth(date=now(); style=Styles(), div_attributes...)
+    current_day = Dates.day(date)
+    month = Dates.monthname(date)
+    ndays = Dates.daysinmonth(date)
+    current_day_style = Styles(style, "background-color" => "gray", "color" => "white")
+    days = map(1:ndays) do day
+        if day == current_day
+            return Card(Centered(day); style=current_day_style)
+        else
+            return Card(Centered(day); style=style)
+        end
+    end
+    grid = Grid(days...; columns="repeat(7, 1fr)")
+    return DOM.div(DOM.h2(month), grid; style=Styles("width" => "400px", "margin" => "5px"))
+end
+
+
+App(()-> CurrentMonth())
+```
+
+Now, we could define the same kind of rendering via overloading `jsrender`, if a date is spliced into a DOM:
+
+```@example 1
+function JSServe.jsrender(session::Session, date::DateTime)
+    return JSServe.jsrender(session, CurrentMonth(date))
+end
+App() do
+    DOM.div(now())
+end
+```
+
+Please note, that `jsrender` is not applied recursively on its own, so one needs to apply it manually on the return value.
+It's not needed for simple divs and other Hyperscript elements, but e.g. `Styles` requires a pass through `jsrender` to do the deduplication etc.

docs/src/index.md

@@ -1,16 +1,16 @@
-`JSServe.jl` is a pretty simple package allowing to render HTML and serve it from within Julia and build up a communication bridge with the Browser. This allows to combine any of your Julia applications with libraries like [WGLMakie](https://docs.makie.org/dev/documentation/backends/wglmakie/index.html#export) and create interactive Dashboards like this:
+`JSServe.jl` is a pretty simple package allowing you to render HTML and serve it from within Julia and build up a communication bridge with the Browser. This allows to combine any of your Julia applications with libraries like [WGLMakie](https://docs.makie.org/dev/documentation/backends/wglmakie/index.html#export) and create interactive Dashboards like this:
 
 ![dashboard](https://user-images.githubusercontent.com/1010467/214651671-2f8174b6-48ab-4627-b15f-e19c35042faf.gif)
 
 JSServe is tightly integrated with WGLMakie, which makes them a great pair for high performance, interactive visualizations.
 If performance is not a high priority, many other plotting/visualization libraries which overload the Julia display system should work with `JSServe.jl` as well.
 
-`JSServe.jl` itself tries to stay out of major choices like the HTML/CSS/Javascript framework to use for creating UIs and Dashboards.
+`JSServe.jl` itself tries to stay out of major choices like the HTML/CSS/Javascript framework to use for creating UIs and Dashboards. Instead, it allows to create modular components and makes it easy to use any CSS/Javascript library.
 
-It uses plain HTML widgets for UI elements where it can, and only to give some base convenience, there is `JSServe.TailwindDashboard` which gives the basic JSServe widgets some nicer look and make it a bit easier to construct complex layouts.
+It uses plain HTML widgets for UI elements where it can, and there are a few styleable components like `Card`, `Grid`, `Row`, `Col` to make it easy to create some more complex dashboards out of the box.
 
-As you can see in `JSServe/src/tailwind-dashboard.jl`, it's just a thin wrapper around the basic `JSServe.jl` widgets, which gives them some class(es) to style them via [TailwindCSS](https://tailwindcss.com/).
-Anyone can do this with their own CSS or HTML/Javascript framework, which should help to create a rich ecosystem of extensions around `JSServe.jl`.
+If you look at the source of those components, one will see that they're very simple and easy to create, which should help to create a rich ecosystem of extensions around `JSServe.jl`.
+Read more about it in [Components](@ref).
 
 ## Quickstart
 
@@ -73,7 +73,7 @@ App() do
 end
 ```
 
-Read more about wrapping libraries in [Tutorial](@ref).
+Read more about wrapping libraries in [Javascript](@ref).
 
 ## Deploying
 

docs/src/animation.md → docs/src/interactions.md

@@ -1,9 +1,9 @@
-# Animating things
+# Interactions
 
 Animations in JSServe are done via Observables.jl, much like it's the case for Makie.jl, so the same docs apply:
 
-https://docs.makie.org/stable/documentation/nodes/index.html
-https://docs.makie.org/stable/documentation/animation/index.html
+* [observables](https://docs.makie.org/stable/documentation/nodes/index.html)
+* [animation](https://docs.makie.org/stable/documentation/animation/index.html)
 
 But lets quickly get started with a JSServe specific example:
 
@@ -18,13 +18,14 @@ App() do session
     value = map(s.value) do x
         return x ^ 2
     end
+    # Record states is an experimental feature to record all states generated in the Julia session and allow the slider to stay interactive in the statically hosted docs!
     return JSServe.record_states(session, DOM.div(s, value))
 end
 ```
 
 The `s.value` is an `Observable` which can be `mapp'ed` to take on new values, and one can insert observables as an input to `DOM.tag` or as any attribute.
-The value of the `observable` will be renedered via `jssrender(session, observable[])`, and then updated whenever the value changes.
-So anything that supports being inserted into the `DOM` can be inside an observable, and the fallback is to use the display system (so plots etc work as well).
+The value of the `observable` will be rendered via `jssrender(session, observable[])`, and then updated whenever the value changes.
+So anything that supports being inserted into the `DOM` can be inside an observable, and the fallback is to use the display system (so plots etc. work as well).
 This way, one can also return `DOM` elements as the result of an observable:
 
 ```@example 1
@@ -64,7 +65,6 @@ App() do session
 end
 ```
 
-
 Likes this one create interactive examples like this:
 
 ```@example 1
@@ -95,7 +95,7 @@ app = App() do session
 end
 ```
 
-As you notice, when exporting this example to the docs which get statically hosted, all interactions requiring Julia ceise to exist.
+As you notice, when exporting this example to the docs which get statically hosted, all interactions requiring Julia cease to exist.
 One way to create interactive examples that stay active is to move the parts that need Julia to Javascript:
 
 ```@example 1

docs/src/tutorial.md → docs/src/javascript-libraries.md

@@ -1,13 +1,15 @@
-# Tutorial
+# Javascript
+
+## Wrapping Javascript Libraries
 
 ```@setup 1
 using JSServe
 JSServe.Page()
 ```
 
 ```@example 1
-leafletjs = JSServe.ES6Module("https://esm.sh/v111/leaflet@1.9.3/es2022/leaflet.js")
-leafletcss = JSServe.Asset("https://unpkg.com/leaflet@1.9.3/dist/leaflet.css")
+leafletjs = JSServe.ES6Module("https://esm.sh/v133/leaflet@1.9.4/es2022/leaflet.mjs")
+leafletcss = JSServe.Asset("https://unpkg.com/leaflet@1.9.4/dist/leaflet.css")
 struct LeafletMap
     position::NTuple{2,Float64}
     zoom::Int