Add js web stuff to landing page + documentation

go/cmd/kjol-web/app/chart.go

@@ -0,0 +1,136 @@
+package app
+
+import (
+	"bytes"
+	"io"
+	"math/rand"
+
+	chart "github.com/wcharczuk/go-chart/v2"
+
+	. "kjol/vdom"
+	ui "kjol/webui"
+)
+
+var chartLabels = []string{"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"}
+
+// fixed initial data so the server SSR and the client's first render match.
+func fixedChartData() []int { return []int{42, 17, 63, 28, 55, 9, 71} }
+
+func randomValues() []int {
+	v := make([]int, len(chartLabels))
+	for i := range v {
+		v[i] = rand.Intn(95) + 5
+	}
+	return v
+}
+
+func renderSVG(c interface {
+	Render(chart.RendererProvider, io.Writer) error
+}) string {
+	var buf bytes.Buffer
+	if c.Render(chart.SVG, &buf) != nil {
+		return "<p class=\"text-danger m-0\">chart error</p>"
+	}
+	return buf.String()
+}
+
+func barSVG(values []int) string {
+	bars := make([]chart.Value, len(values))
+	for i, v := range values {
+		bars[i] = chart.Value{Value: float64(v), Label: chartLabels[i%len(chartLabels)]}
+	}
+	return renderSVG(&chart.BarChart{
+		Title:      "Weekly values (bar)",
+		TitleStyle: chart.Style{FontSize: 15},
+		Background: chart.Style{Padding: chart.Box{Top: 48, Left: 16, Right: 16, Bottom: 16}},
+		Height:     320, BarWidth: 48, Bars: bars,
+	})
+}
+
+func pieSVG(values []int) string {
+	vs := make([]chart.Value, len(values))
+	for i, v := range values {
+		vs[i] = chart.Value{Value: float64(v), Label: chartLabels[i%len(chartLabels)]}
+	}
+	return renderSVG(&chart.PieChart{
+		Title:      "Share by day (pie)",
+		TitleStyle: chart.Style{FontSize: 15},
+		Background: chart.Style{Padding: chart.Box{Top: 48}},
+		Width:      320, Height: 320, Values: vs,
+	})
+}
+
+//gowasm:page /wasm/chart static layout=app
+func ChartPage(d Deps) func() *VNode {
+	data := NewSignal(fixedChartData())
+
+	return func() *VNode {
+		values := data.Get()
+
+		return docPage("Rendering", "SSR & hydration",
+			"A static route is rendered to HTML by the server, so the page is complete before any "+
+				"WebAssembly has downloaded. The same component then runs in the browser, adopts the markup "+
+				"that is already there, and takes over. One function, two runtimes.",
+
+			docSection("the-directive", "Marking a route static",
+				prose("static on the page directive is what puts a route in the server's pre-render set. Leave "+
+					"it off and the route renders on the client only — which is the right choice when the page "+
+					"is behind a login, or its content depends on something only the browser knows."),
+				code("app/chart.go", chartSnippet),
+				note("Hydration adopts, it does not rebuild",
+					"The client renders the same tree the server did and walks the existing DOM alongside it, "+
+						"wiring event handlers to the nodes that are already on the page. If the two trees "+
+						"disagree, the CLIENT wins — a stale server binary should not be able to pin a wrong "+
+						"class onto the page forever."),
+			),
+
+			docSection("charts", "A worked example: charts",
+				prose("These charts are SVG produced by go-chart — a plain Go library that knows nothing about "+
+					"the browser. The server draws them and ships the markup inline; there is no chart "+
+					"JavaScript, and no canvas that has to wait for the client to boot before it shows anything."),
+				prose("Shuffle re-runs the same drawing code in the browser. The first render came from the "+
+					"server and the next one comes from WebAssembly, and the page cannot tell the difference."),
+
+				Div(Attr("class", "mt-4"),
+					ui.Button(ui.ButtonProps{Color: ui.ButtonPrimary, Icon: "chart-column", Text: "Shuffle data",
+						OnClick: func() { data.Set(randomValues()) }}),
+				),
+				Div(Attr("class", "mt-4 grid gap-4 lg:grid-cols-12"),
+					Div(Attr("class", "lg:col-span-7 rounded-default border border-line bg-surface p-3 shadow-xs overflow-auto"), Raw(barSVG(values))),
+					Div(Attr("class", "lg:col-span-5 rounded-default border border-line bg-surface p-3 shadow-xs overflow-auto"), Raw(pieSVG(values))),
+				),
+
+				note("go-chart lives in the EXAMPLE, not in kjol",
+					"The engine is standard-library-only. This example is its own Go module precisely so a "+
+						"charting dependency it happens to want does not become a dependency of everyone who "+
+						"uses the framework."),
+			),
+
+			docSection("api", "Reference",
+				apiTable(
+					apiRow{"//gowasm:page /path static", "Pre-render this route on the server, then hydrate it."},
+					apiRow{"vdom.RenderHTML", "Render a tree to an HTML string. This is what the server calls."},
+					apiRow{"wasmruntime.Hydrate", "Adopt server-rendered DOM instead of building it. The client's entry point for a static route."},
+					apiRow{"vdom.Raw", "Insert markup verbatim — how the server-drawn SVG gets in. The reconciler clears it correctly when the element is reused."},
+				),
+			),
+		)
+	}
+}
+
+const chartSnippet = `//gowasm:page /wasm/chart static layout=app
+func ChartPage(d Deps) func() *VNode {
+    data := NewSignal(fixedChartData())
+
+    return func() *VNode {
+        // go-chart draws an SVG string — on the server for the first paint,
+        // and in the browser for every render after that.
+        return Div(
+            ui.Button(ui.ButtonProps{
+                Text:    "Shuffle data",
+                OnClick: func() { data.Set(randomValues()) },
+            }),
+            Div(Raw(barSVG(data.Get()))),
+        )
+    }
+}`