Add landing page for kjol, documentation

go/cmd/examples/go-wasm-web/app/chart.go

@@ -63,19 +63,74 @@ func pieSVG(values []int) string {
 //gowasm:page /chart static layout=app
 func ChartPage(d Deps) func() *VNode {
 	data := NewSignal(fixedChartData())
+
 	return func() *VNode {
 		values := data.Get()
-		return Div(Attr("class", "space-y-6"),
-			Div(
-				H2(Attr("class", "text-2xl font-semibold tracking-tight text-text-heading"), Text("Charts — go-chart (SSR + hydrate)")),
-				P(Attr("class", "mt-1 text-neutral-500"),
-					Text("Rendered to SVG on the server, hydrated on the client; Shuffle re-renders client-side.")),
+
+		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."),
 			),
-			ui.Button(ui.ButtonProps{Color: ui.ButtonPrimary, Text: "Shuffle data", OnClick: func() { data.Set(randomValues()) }}),
-			Div(Attr("class", "grid gap-4 lg:grid-cols-12"),
-				Div(Attr("class", "lg:col-span-7 rounded-default border border-neutral-200 bg-white p-3 shadow-xs overflow-auto"), Raw(barSVG(values))),
-				Div(Attr("class", "lg:col-span-5 rounded-default border border-neutral-200 bg-white p-3 shadow-xs overflow-auto"), Raw(pieSVG(values))),
+
+			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 /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()))),
+        )
+    }
+}`