@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/site/pages/pulse/index.wd

@@ -88,7 +88,7 @@ Sampled UTC, this morning
 **Source**
 
 ::: div .stat-value
-:fetch
+\:fetch
 :::
 
 Live JSON endpoint

package/site/pages/settings/index.wd

@@ -0,0 +1,97 @@
+---
+html: true
+title: Bound controls: a select, a radio group and a checkbox
+description: Outside a :form, the three field directives bind straight to a declared :state, so a settings panel drives :if regions with no form and no JavaScript of your own.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# Bound controls
+
+`:select`, `:radio` and `:checkbox` mean two things, and where they sit decides which. Inside a `:form` they are form fields, submitted by name. Outside one they bind to a declared `:state` the way `:bind` and `:slider` already do: move the control and the state changes, change the state and the control moves.
+
+</section>
+
+<section>
+
+## A settings panel
+
+:state density = "Comfortable"
+:state theme_pick = "System"
+:state previews = true
+
+**Density**
+
+:select density
+- Compact
+- Comfortable
+- Spacious
+
+**Colour**
+
+:radio theme_pick
+- System
+- Light
+- Dark
+
+**Previews**
+
+:checkbox previews
+- Show image previews
+
+</section>
+
+<section>
+
+## What the panel drives
+
+Every region below reads the same state the controls write.
+
+:if density == "Compact"
+Compact: rows sit tight together.
+:else if density == "Spacious"
+Spacious: rows get room to breathe.
+:else
+Comfortable: the default spacing.
+:endif
+
+:if theme_pick == "System"
+Following the operating system's colour scheme.
+:else
+Forcing **{ theme_pick }** regardless of the system setting.
+:endif
+
+:if previews
+Image previews are on.
+:else
+Image previews are off, so the list loads text only.
+:endif
+
+Settings as one line each: **{ density }**, **{ theme_pick }**, previews { previews }.
+
+:button "Reset to defaults" -> density reset; theme_pick reset; previews reset
+
+</section>
+
+<section>
+
+## The rules
+
+- The state has to exist first. A bound field with no matching `:state` is a compile error that names both readings, so a typo can never become a silently inert control.
+- A bound `:radio` group carries the chosen option's text; the group keeps a shared `name` so the browser makes it mutually exclusive.
+- A bound `:checkbox` carries a **boolean**, so it takes exactly one `- Label` line, the label to show beside it. The multi-value checkbox group is the in-form behavior and is unchanged.
+- Inside a `:form` nothing changed at all, even if a `:state` of the same name happens to exist elsewhere on the page.
+
+<a class="btn primary" href="/docs/#bound-controls-outside-a-form">Read the docs on bound controls</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/site/pages/showcase/index.wd

@@ -96,7 +96,7 @@ Darkmown's whole pitch is weight. A static page ships **zero** framework JavaScr
 
 ::: card .sc-scale
 - **Static Darkmown page** — `0 KB` framework JS. Forever.
-- **Reactive Darkmown page** — one shared `~7.7 KB` gzipped runtime, no per-component bundles.
+- **Reactive Darkmown page** — one shared `~6.6 KB` gzipped runtime, no per-component bundles.
 - **A typical SPA** — ships a framework runtime in the **~15–60 KB** gzipped range *before* your app code, on every page (Alpine ~15 KB, Vue ~18 KB runtime, React 19 ~59 KB).
 :::
 
@@ -160,6 +160,42 @@ Prefer to see each feature in isolation? These pages tour the building blocks th
 [Open →](/markdown/)
 :::
 
+::: card .sc-mini
+**Reactive links**: a destination that follows state.
+
+[Open →](/attr-binding/)
+:::
+
+::: card .sc-mini
+**URL state**: `from-url`, a filter you can share.
+
+[Open →](/url-state/)
+:::
+
+::: card .sc-mini
+**Bound controls**: select, radio, checkbox, no form.
+
+[Open →](/settings/)
+:::
+
+::: card .sc-mini
+**Server errors**: what the API actually said.
+
+[Open →](/api-errors/)
+:::
+
+::: card .sc-mini
+**File upload**: a `:form` that posts multipart.
+
+[Open →](/upload/)
+:::
+
+::: card .sc-mini
+**Branch state**: a `:state` inside a closed `:if`.
+
+[Open →](/branch-state/)
+:::
+
 </div>
 
 </section>

package/site/pages/upload/index.wd

@@ -0,0 +1,63 @@
+---
+html: true
+title: File upload: a :form that posts multipart
+description: A :form containing a file field submits as multipart FormData instead of a urlencoded body, so the file itself travels. The failure path renders the server's own message and its field-level errors.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# File upload
+
+A urlencoded body can only carry a file's **name**. A `:form` that contains a file field now declares `enctype="multipart/form-data"` and the runtime posts the `FormData` itself, letting the browser write the multipart boundary. Nothing else about the form changes.
+
+</section>
+
+<section>
+
+## Pick a file and send it
+
+:form into reply action="/api/upload/"
+:input photo type=file required
+:input caption placeholder="A caption (optional)"
+:submit "Upload"
+:endform
+
+:if reply
+Uploaded **{ reply.name }**, { reply.size } bytes, type `{ reply.type }`.
+:if reply.caption
+Caption: { reply.caption }
+:endif
+:endif
+
+:if reply_error
+**{ reply_error }**
+:if reply_error_body
+The server also said which field was wrong: { reply_error_body.fields.photo }
+:endif
+:endif
+
+Submit with no file to see the failure path: the endpoint answers `422` with a JSON body, and the page renders the server's own sentence rather than "HTTP 422".
+
+</section>
+
+<section>
+
+## The rules
+
+- A file field makes the whole form multipart. The compiler writes the `enctype` for the browser's native submit, and the runtime sends the `FormData` with **no** content-type of its own so the boundary is correct.
+- Bound controls inside the form (a `:bind`, a bound `:select`) carry no `name`, so `FormData` never sees them. On the multipart path they are appended by their state key rather than silently dropped.
+- A file field with `method="get"` is a compile error. A GET request has no body, so only the file's name would ever travel, the kind of failure that looks like it worked.
+
+<a class="btn primary" href="/docs/#file-upload">Read the docs on file upload</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/site/pages/url-state/index.wd

@@ -0,0 +1,70 @@
+---
+html: true
+title: The URL is state: :state … from-url
+description: A filter that survives a reload and travels in a shared link. from-url mirrors a :state into the query string with replaceState, drops the parameter when the value is back at its default, and re-reads on back and forward.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# The URL is state
+
+A filter nobody can link to is half a feature. Add `from-url` to a `:state` and the value lives in the query string as well as in memory: reload keeps it, a shared link arrives with it applied, and back and forward move through it.
+
+</section>
+
+<section>
+
+## Search and filter
+
+:state q = "" from-url
+:state tier = "all" from-url
+
+:bind q placeholder="Search products"
+
+:radio tier
+- all
+- budget
+- premium
+
+:state products = [
+  { "name": "Aurora Lamp", "price": 49, "tier": "budget" },
+  { "name": "Briza Fan", "price": 89, "tier": "budget" },
+  { "name": "Cove Shelf", "price": 240, "tier": "premium" },
+  { "name": "Dune Rug", "price": 310, "tier": "premium" }
+]
+
+Tier **{ tier }**, search "{ q }".
+
+@loop products into p where p.name contains q
+- **{ p.name }** · { p.price | money } ({ p.tier })
+@empty
+Nothing matches that search.
+@endloop
+
+Type in the box and watch the address bar. Then reload the page: the search and the tier come back. Copy the URL into a new tab and it opens on the same view. The tier radio is a second key riding along in the same URL; it is shown above the list rather than wired into the filter, so you can see two `from-url` keys travel together.
+
+</section>
+
+<section>
+
+## The rules
+
+- The parameter is named after the state key. A section-scoped key like `cart:items` becomes `cart.items`, so the name is always readable and always unique.
+- A value equal to its declared seed **drops** its parameter, so the default page keeps a clean URL.
+- Writes go through `history.replaceState`, so filtering never fills the back button with one entry per keystroke.
+- Combine it with `persist` and the precedence is URL first, then the stored value, then the seed, so a link you were sent wins over what this browser remembers.
+- `from-url` belongs to `:state` only. A `:store` is shared by every page and every tab, while a query parameter belongs to one page's address, so putting `from-url` on a `:store` is a compile error rather than a guess.
+
+<a class="btn primary" href="/docs/#url-as-state-from-url">Read the docs on URL as state</a>
+
+</section>
+
+</main>
+
+@include /footer.wd