weft 0.1.0

data/docs/examples/lazy-loading.md

@@ -0,0 +1,96 @@
+# Lazy Loading
+
+A placeholder that fills itself with real content the moment it scrolls into view. Expensive sections — big queries, slow aggregations — stay out of the initial render, and the page arrives fast.
+
+This is Weft's take on [htmx's lazy-load example](https://htmx.org/examples/lazy-load/), where a graph is fetched only when revealed. The shape is identical: a lightweight placeholder carries the wiring, and the server renders the heavy part on demand. In Weft, the heavy part is simply a component.
+
+## The components
+
+```ruby
+QUARTERLY_REVENUE = {
+  2025 => { "Q1" => "$418,200", "Q2" => "$473,900", "Q3" => "$391,400", "Q4" => "$512,750" }
+}.freeze
+
+class RevenueTable < Weft::Component
+  builder_method :revenue_table
+
+  attribute :year, default: 2025
+
+  def build(attributes = {})
+    super
+    table do
+      thead { tr { th "Quarter"; th "Revenue" } }
+      tbody do
+        QUARTERLY_REVENUE.fetch(attrs.year).each do |quarter, amount|
+          tr { td quarter; td amount }
+        end
+      end
+    end
+  end
+end
+
+class AnnualReport < Weft::Component
+  builder_method :annual_report
+
+  attribute :year, default: 2025
+
+  def build(attributes = {})
+    super
+    h2 "#{attrs.year} annual report"
+    para "Commentary, highlights, and everything else the reader scrolls through " \
+         "before the numbers. The revenue table below is expensive to produce, " \
+         "so it loads only when it comes into view."
+    div lazy: RevenueTable, with: { year: attrs.year } do
+      para "Loading revenue…"
+    end
+  end
+end
+```
+
+(The `QUARTERLY_REVENUE` hash stands in for your data layer — in real life this is the query you'd rather not run on every page view.)
+
+## How it works
+
+**The placeholder is an ordinary element with one extra kwarg.** [`lazy:`](../dsl.md#shorthands) is a preset over the [`loads:`](../dsl.md#loads) machinery: trigger `:visible`, swap `:fill`, target `:self`. When the div scrolls into view, fetch `RevenueTable` and swap it into the div's interior. Because trigger, swap, *and* target all have an obvious right answer here, the call site needs nothing beyond the component class and its attrs.
+
+**The div's children are the loading state.** Because the swap is `:fill` (`innerHTML`), the placeholder element itself survives; only its contents — the "Loading revenue…" paragraph — are replaced by the fetched component. Whatever you put in the block is what users see until the content arrives.
+
+**`:visible` means once.** The semantic trigger expands to htmx's `revealed`, which fires a single time when the element first enters the viewport. The wrapper keeps its wiring after the swap, but no re-fetch loop follows.
+
+**`with:` passes the wire state along.** The placeholder hands its own `year` down to the loaded component (`with: { year: attrs.year }`), and the value travels in the URL — visible below. If you omit `with:`, the enclosing component's attrs are passed by default.
+
+## On the wire
+
+The initial render (or `GET /_components/annual_report?year=2025`) contains the placeholder, wired and waiting:
+
+```html
+<div id="annual-report-2025">
+  <h2>2025 annual report</h2>
+  <p>Commentary, highlights, and everything else the reader scrolls through …</p>
+  <div hx-get="/_components/revenue_table?year=2025" hx-swap="innerHTML"
+       hx-target="this" hx-trigger="revealed">
+    <p>Loading revenue…</p>
+  </div>
+</div>
+```
+
+Scrolling it into view issues `GET /_components/revenue_table?year=2025`, and the response fills the placeholder:
+
+```html
+<div id="revenue-table-2025">
+  <table>
+    <thead><tr><th>Quarter</th><th>Revenue</th></tr></thead>
+    <tbody>
+      <tr><td>Q1</td><td>$418,200</td></tr>
+      <tr><td>Q2</td><td>$473,900</td></tr>
+      <!-- … -->
+    </tbody>
+  </table>
+</div>
+```
+
+## Related
+
+- [Infinite Scroll](infinite-scroll.md) — the same `:visible` trigger, used repeatedly to grow a table page by page.
+- [Click to Load](click-to-load.md) — deferred loading where the user asks for more, instead of scrolling to it.
+- The [shorthands table](../dsl.md#shorthands) and the [trigger values](../dsl.md#trigger-values) in the DSL reference.

data/docs/examples/live-ticker.md

@@ -0,0 +1,91 @@
+# Live Ticker
+
+A panel of live numbers — a server clock, a drifting gauge — that updates itself every couple of seconds without being asked. The server holds a connection open and pushes fresh renderings down it; the client never polls.
+
+This one has no direct counterpart in [htmx's examples catalog](https://htmx.org/examples/), which doesn't carry a server-sent-events demo — htmx covers SSE through its [SSE extension](https://htmx.org/extensions/sse/) rather than a catalog page. Weft builds on that same extension, and wraps the whole arrangement — the stream endpoint, the connection attributes, the event framing, even loading the extension script — into one declaration: [`pushes every: 2`](../dsl.md#pushes--the-server-sends-updates).
+
+## The components
+
+```ruby
+# A drifting gauge: a small random walk that stands in for any live number
+# your app can read on demand — active sessions, queue depth, a sensor.
+module VisitorGauge
+  class << self
+    def reading
+      @reading = (@reading || 142) + rand(-9..9)
+    end
+  end
+end
+
+class LiveTicker < Weft::Component
+  builder_method :live_ticker
+
+  pushes every: 2
+
+  def build(attributes = {})
+    super
+    para "Server time: #{Time.now.strftime('%H:%M:%S')}"
+    para "Visitors right now: #{VisitorGauge.reading}"
+  end
+end
+```
+
+## How it works
+
+**One declaration, both ends of the wire.** `pushes every: 2` does two things at once. Server-side, the Router auto-generates an SSE endpoint for the component at its own path plus a stream suffix — `/_components/live_ticker/_stream` — where it re-renders the component every 2 seconds and pushes the result down the open connection. Client-side, the component renders with the htmx SSE attributes (`hx-ext="sse"`, `sse-connect`, `sse-swap`) already on its wrapper, so the connection opens as soon as the component lands in a page. (The `_stream` suffix is configurable — see [`stream_suffix`](../configuration.md#stream_suffix).)
+
+**Pushed frames fill the component's interior.** Unlike a [`refreshes`](../dsl.md#refreshes--the-client-re-fetches) poll, which replaces the whole component, a pushed frame swaps `innerHTML`: the wrapper element *holds the SSE connection*, so it must persist while its contents are replaced underneath it. That's also why each frame's payload is the component's children only, with no wrapper div.
+
+**Events are named after the component.** Each frame arrives as `event: live-ticker` — the component's DOM id — and the wrapper's `sse-swap="live-ticker"` subscribes to exactly that name. The two are generated from the same value, so they always agree.
+
+**New subscribers get an immediate snapshot.** The first frame is pushed the moment the connection opens, then the 2-second cadence begins. A page that renders the component and connects a beat later doesn't sit stale for one interval — and a dropped connection that reconnects catches up instantly.
+
+**The extension script ships itself.** Pages include the htmx SSE extension automatically when any registered component declares `pushes` — the [`include_sse_ext`](../configuration.md#include_sse_ext) setting, whose `:auto` default means apps without SSE components never ship the extra script and apps with them never have to remember it.
+
+## On the wire
+
+The initial render (or `GET /_components/live_ticker`) — the wrapper carries the connection wiring, and usable content is already inside:
+
+```html
+<div id="live-ticker" hx-ext="sse" sse-connect="/_components/live_ticker/_stream"
+     sse-swap="live-ticker" hx-swap="innerHTML">
+  <p>Server time: 15:39:53</p>
+  <p>Visitors right now: 146</p>
+</div>
+```
+
+The page it sits in has the extension script in its `<head>`, included automatically alongside htmx itself:
+
+```html
+<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-…" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/htmx-ext-sse@2.2.2/sse.js"></script>
+```
+
+Connecting to the stream — here with `curl -N`, held open for seven seconds — answers with SSE headers and then a frame every 2 seconds, the first one immediately:
+
+```
+HTTP/1.1 200 OK
+content-type: text/event-stream;charset=utf-8
+cache-control: no-cache
+transfer-encoding: chunked
+
+event: live-ticker
+data:   <p>Server time: 15:39:53</p>
+data:   <p>Visitors right now: 144</p>
+
+event: live-ticker
+data:   <p>Server time: 15:39:55</p>
+data:   <p>Visitors right now: 151</p>
+
+event: live-ticker
+data:   <p>Server time: 15:39:57</p>
+data:   <p>Visitors right now: 159</p>
+```
+
+Each multi-line rendering becomes consecutive `data:` lines in one event, per the SSE format; htmx reassembles them and swaps the result into the wrapper.
+
+## Related
+
+- [Progress Bar](progress-bar.md) — the polling counterpart: the client re-fetches on a timer instead of holding a connection.
+- [`pushes`](../dsl.md#pushes--the-server-sends-updates) in the DSL reference; [`stream_suffix`](../configuration.md#stream_suffix) and [`include_sse_ext`](../configuration.md#include_sse_ext) in configuration.
+- A component with attributes streams too — its wire state rides the `sse-connect` URL as query parameters, so each subscriber gets frames for *its* instance.

data/docs/examples/modal-dialog.md

@@ -0,0 +1,88 @@
+# Modal Dialog
+
+A button opens a dialog floating over a dimmed page; pressing Close — or clicking the dimmed backdrop — makes it go away. The dialog is a component fetched on demand, and closing it is simply removing it from the DOM.
+
+This is Weft's take on [htmx's custom modal example](https://htmx.org/examples/modal-custom/). htmx's version reaches for hyperscript to wire up the close behavior; in Weft the close is a [`dismisses`](../dsl.md#dismisses--remove-from-the-dom) action, so there's no JavaScript beyond what Weft already ships. (htmx's catalog also carries UIkit and Bootstrap modal variants — integrating with a CSS framework's modal machinery is out of scope here.)
+
+## The components
+
+```ruby
+class TourDialog < Weft::Component
+  builder_method :tour_dialog
+
+  dismisses :close
+
+  def build(attributes = {})
+    super
+    # Underlay and panel are siblings, so clicks on the panel never reach
+    # the underlay. Inline styles are the minimum to dim and center —
+    # real styling belongs in your stylesheet.
+    div action: :close,
+        style: "position: fixed; inset: 0; background: rgba(0, 0, 0, 0.4);"
+    div style: "position: fixed; top: 20%; left: 50%; transform: translateX(-50%); " \
+               "background: white; padding: 1.5rem 2rem; border-radius: 6px;" do
+      h3 "Book a tour"
+      para "Our next open house is Saturday at noon. Come see the workshop, " \
+           "meet the team, and try the tools yourself."
+      button "Close", action: :close
+    end
+  end
+end
+
+class TourPromo < Weft::Component
+  builder_method :tour_promo
+
+  def build(attributes = {})
+    super
+    button "Book a tour", modal: TourDialog, target: "#modal-slot"
+    div id: "modal-slot"
+  end
+end
+```
+
+## How it works
+
+**Opening is a load into a stable slot.** [`modal:`](../dsl.md#shorthands) presets trigger `:click` and swap `:fill`; the call site supplies the target. Clicking the button fetches `TourDialog` and fills the empty `#modal-slot` div with it. The slot is permanent page structure — it outlives any dialog placed in it, so the modal can be opened again after closing.
+
+**Closing is a dismissal.** `dismisses :close` declares a DELETE action whose swap removes the component from the page entirely — and for a modal, removed from the DOM *is* closed. The dialog vanishes, the slot div stays, and the page underneath was never touched. Give the dismissal a block (`dismisses :close do |attrs| ... end`) if closing should also do something server-side, like recording that the tour offer was seen.
+
+**The underlay closes too — same action, different element.** [`action:`](../dsl.md#action) isn't just for buttons: on the underlay div it expands to exactly the same wiring as the Close button, and htmx's default trigger for a div is a click. Because the underlay and the content panel are *siblings* — the underlay covers the viewport, the panel floats above it — a click on the panel never bubbles to the underlay, so only clicks on the dimmed backdrop dismiss.
+
+**Closing is a round trip.** htmx's custom modal closes instantly, client-side; Weft's close asks the server first. That's the trade for writing no close-handling JavaScript: a request on the wire per dismissal, in exchange for one declaration and a place to hang side effects. For a modal on a reasonable connection the difference isn't perceptible, but it's worth knowing which one you're getting.
+
+## On the wire
+
+The initial render — a wired trigger button and an empty slot:
+
+```html
+<div id="tour-promo">
+  <button hx-get="/_components/tour_dialog" hx-swap="innerHTML"
+          hx-target="#modal-slot" hx-trigger="click">Book a tour</button>
+  <div id="modal-slot"></div>
+</div>
+```
+
+Clicking the button issues `GET /_components/tour_dialog`, and the dialog fills the slot. Underlay and Close button carry identical dismissal wiring:
+
+```html
+<div id="tour-dialog">
+  <div style="position: fixed; inset: 0; background: rgba(0, 0, 0, 0.4);"
+       hx-delete="/_components/tour_dialog/close" hx-target="#tour-dialog"
+       hx-swap="delete" hx-vals="{}"></div>
+  <div style="position: fixed; top: 20%; left: 50%; transform: translateX(-50%); background: white; padding: 1.5rem 2rem; border-radius: 6px;">
+    <h3>Book a tour</h3>
+    <p>Our next open house is Saturday at noon. Come see the workshop,
+       meet the team, and try the tools yourself.</p>
+    <button hx-delete="/_components/tour_dialog/close" hx-target="#tour-dialog"
+            hx-swap="delete" hx-vals="{}">Close</button>
+  </div>
+</div>
+```
+
+Clicking either one issues `DELETE /_components/tour_dialog/close`. The response is a `200` whose body htmx discards — a `delete` swap removes the target element no matter what came back — leaving `#modal-slot` empty again.
+
+## Related
+
+- [Browser Dialogs](browser-dialogs.md) — when a native `confirm()` box is dialog enough.
+- [Keyboard Shortcuts](keyboard-shortcuts.md) — the [`trigger:`](../dsl.md#trigger) grammar that could add Escape-to-close to this dialog.
+- [`dismisses`](../dsl.md#dismisses--remove-from-the-dom) and the [shorthands table](../dsl.md#shorthands) in the DSL reference.

data/docs/examples/progress-bar.md

@@ -0,0 +1,138 @@
+# Progress Bar
+
+A Start button kicks off a background job, a progress bar advances as the server reports the work getting done, and a Restart button appears when it finishes — the whole lifecycle driven by one polling component.
+
+This is Weft's take on [htmx's progress-bar example](https://htmx.org/examples/progress-bar/), with the same ARIA-annotated bar and the same smooth CSS-transition movement. htmx builds it from three hand-wired pieces — a start button, a polling wrapper, and an `HX-Trigger`-based handoff to stop the polling. In Weft it's one component with two declarations: `performs :start` for the kickoff, `refreshes every: 1` for the watching.
+
+## The components
+
+```ruby
+# A fake background job: each status check advances the work by 20 points.
+# Stands in for reading real progress from your job layer — a Sidekiq
+# status hash, an ActiveJob progress record, whatever your app uses.
+module FakeJob
+  class << self
+    def start!
+      @state = "running"
+      @progress = 0
+    end
+
+    # Report the current status, then advance the fake work so the next
+    # check sees more of it done.
+    def check
+      snapshot = { state: state, progress: progress }
+      advance if state == "running"
+      snapshot
+    end
+
+    def state = @state ||= "idle"
+    def progress = @progress ||= 0
+
+    private
+
+    def advance
+      @progress += 20
+      @state = "complete" if @progress >= 100
+    end
+  end
+end
+
+class JobMonitor < Weft::Component
+  builder_method :job_monitor
+
+  refreshes every: 1
+
+  performs :start do |_attrs|
+    FakeJob.start!
+    nil
+  end
+
+  def build(attributes = {})
+    super
+    job = FakeJob.check
+    case job[:state]
+    when "idle"
+      button "Start Job", action: :start
+    when "running"
+      h3 "Running", id: "pblabel"
+      progress_bar(job[:progress])
+    else
+      h3 "Complete", id: "pblabel"
+      progress_bar(100)
+      button "Restart Job", action: :start
+    end
+  end
+
+  private
+
+  def progress_bar(percent)
+    div class: "progress", role: "progressbar", "aria-valuemin": "0",
+        "aria-valuemax": "100", "aria-valuenow": percent.to_s,
+        "aria-labelledby": "pblabel",
+        style: "max-width:20rem; background:#e5e7eb; border-radius:4px" do
+      div class: "progress-bar",
+          style: "width:#{percent}%; height:1.25rem; background:#2563eb; " \
+                 "border-radius:4px; transition:width 1s linear"
+    end
+  end
+end
+```
+
+## How it works
+
+**One component renders the whole lifecycle.** `build` checks the job and renders whichever state it finds: a Start button, the advancing bar, or the finished bar with its Restart affordance. Because [`refreshes every: 1`](../dsl.md#refreshes--the-client-re-fetches) puts the polling wiring on the component's wrapper element, every poll replaces the component wholesale (`outerHTML`) — so the UI moves between states with no extra plumbing. When the server flips the job to complete, the next poll simply renders the completed state.
+
+**Starting is an ordinary action.** The Start and Restart buttons both wire to [`performs :start`](../dsl.md#performs--user-initiated-actions), whose callable kicks the fake job and ends with `nil` — the re-render after the action shows the freshly started bar at 0%. htmx's version needs the start response to *establish* the polling wrapper; in Weft the wiring is declared on the class, so it's already present in every rendering, initial page included.
+
+**The bar is just a styled div, meaningfully annotated.** The outer div carries `role="progressbar"` with `aria-valuenow`/`-valuemin`/`-valuemax` (mirroring htmx's markup), and the inner div's inline `width` is the percentage. The `transition: width 1s linear` matches the 1-second poll cadence, so the bar glides continuously instead of jumping — the same trick as htmx's "smooth" variant.
+
+**Progress advances on each check.** `FakeJob.check` reports the current status and then moves the fake work forward, so five polls walk the bar 0 → 20 → 40 → 60 → 80 → done. In your app, `check` becomes a read of real job progress and the cadence stops being lockstep — the component doesn't care either way.
+
+**One honest limitation:** the refresh wiring is class-level and unconditional in this release, so the completed (and idle) states keep polling once per second even though nothing will change until someone clicks Restart. htmx's original stops polling at 100% via an `HX-Trigger` handoff; Weft currently has no per-render way to switch the timer off.
+
+## On the wire
+
+The initial render (or `GET /_components/job_monitor`) — note the polling wiring already on the wrapper:
+
+```html
+<div id="job-monitor" hx-get="/_components/job_monitor" hx-trigger="every 1s" hx-swap="outerHTML">
+  <button hx-post="/_components/job_monitor/start" hx-target="#job-monitor"
+          hx-swap="outerHTML" hx-vals="{}">Start Job</button>
+</div>
+```
+
+Clicking Start issues `POST /_components/job_monitor/start`, and the response is the running state at 0%:
+
+```html
+<div id="job-monitor" hx-get="/_components/job_monitor" hx-trigger="every 1s" hx-swap="outerHTML">
+  <h3 id="pblabel">Running</h3>
+  <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="100"
+       aria-valuenow="0" aria-labelledby="pblabel"
+       style="max-width:20rem; background:#e5e7eb; border-radius:4px">
+    <div class="progress-bar" style="width:0%; height:1.25rem; background:#2563eb; border-radius:4px; transition:width 1s linear"></div>
+  </div>
+</div>
+```
+
+Each poll — `GET /_components/job_monitor`, once per second — returns the same shape further along (`aria-valuenow="20"`, `width:20%`, then 40, 60, 80…). The fifth poll finds the job complete:
+
+```html
+<div id="job-monitor" hx-get="/_components/job_monitor" hx-trigger="every 1s" hx-swap="outerHTML">
+  <h3 id="pblabel">Complete</h3>
+  <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="100"
+       aria-valuenow="100" aria-labelledby="pblabel"
+       style="max-width:20rem; background:#e5e7eb; border-radius:4px">
+    <div class="progress-bar" style="width:100%; height:1.25rem; background:#2563eb; border-radius:4px; transition:width 1s linear"></div>
+  </div>
+  <button hx-post="/_components/job_monitor/start" hx-target="#job-monitor"
+          hx-swap="outerHTML" hx-vals="{}">Restart Job</button>
+</div>
+```
+
+Restart POSTs the same `:start` action and the cycle begins again. (The completed fragment still carries `hx-trigger="every 1s"` — the limitation noted above, visible on the wire.)
+
+## Related
+
+- [Live Ticker](live-ticker.md) — when the server should *push* updates instead of being polled.
+- [`refreshes`](../dsl.md#refreshes--the-client-re-fetches) and [`performs`](../dsl.md#performs--user-initiated-actions) in the DSL reference.
+- htmx's original polls every 600ms — `refreshes every: 0.6` expresses exactly that. This example keeps a 1-second cadence and matches the bar's `transition` duration to it.

data/docs/examples/reset-user-input.md

@@ -0,0 +1,101 @@
+# Reset User Input
+
+An add-a-comment form beneath a comment list: submit, and the new comment appears in the list while the form comes back empty, ready for the next thought. Nothing *resets* the form — a new one arrives.
+
+This is Weft's take on [htmx's reset-user-input example](https://htmx.org/examples/reset-user-input/), though "take on" oversells it. htmx needs `hx-on::after-request="this.reset()"` because the form that posted is still sitting in the DOM afterwards, holding the user's text. A Weft action re-renders the whole component from server state, so the swapped-in form never had text in it to begin with. There's nothing to do — this page is about why.
+
+## The components
+
+```ruby
+GUEST_COMMENTS = [
+  { author: "Rosa", body: "Lovely event — count me in for next year." }
+]
+
+class CommentSection < Weft::Component
+  builder_method :comment_section
+
+  attribute :author
+  attribute :body
+
+  performs :post do |attrs|
+    author = attrs.author.to_s.strip
+    body = attrs.body.to_s.strip
+    GUEST_COMMENTS << { author: author, body: body } unless author.empty? || body.empty?
+    { author: nil, body: nil }
+  end
+
+  def build(attributes = {})
+    super
+    ul do
+      GUEST_COMMENTS.each do |comment|
+        li { strong "#{comment[:author]}: "; text_node comment[:body] }
+      end
+    end
+    form(action: :post) do
+      div do
+        label "Name ", for: "author"
+        input type: "text", name: "author", id: "author"
+      end
+      div do
+        label "Comment ", for: "body"
+        input type: "text", name: "body", id: "body"
+      end
+      input type: "submit", value: "Add Comment"
+    end
+  end
+end
+```
+
+(The `GUEST_COMMENTS` array stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**The response replaces the form, typed text and all.** `build` renders the list from the store and the inputs with no `value:` at all — so every render of this component has empty fields. The action's `outerHTML` swap replaces the old elements wholesale: the inputs holding the typed text leave the DOM, and fresh, empty ones arrive in the same response that shows the new comment in the list. What htmx solves with an after-request reset handler, the render model here dissolves.
+
+**Clearing the params in the return keeps the identity stable.** The callable ends with `{ author: nil, body: nil }` — a returned hash merges into the attrs for the re-render ([the callable contract](../dsl.md#the-callable-contract)), and Weft derives a component's DOM id from its first declared attribute. Cleared, the wrapper comes back as the same `#comment-section` the htmx wiring points at; left populated, the submitted name would leak into the re-rendered component's identity.
+
+**Blank submits are the callable's problem, and it handles them.** The browser happily posts `author=&body=`; the strip-and-check guard appends nothing, and the response is simply the current state re-rendered. Client-side `required` attributes would be a fine courtesy on top, but the server-side guard is the one that holds.
+
+**No JavaScript, no reset handler.** `form(action: :post)` also emits plain `action`/`method` attributes, so without htmx the same POST works as a full-page form submit — and a freshly rendered page has empty fields for exactly the same reason the fragment does.
+
+## On the wire
+
+The initial render (or `GET /_components/comment_section`) — one comment in the list, the form's inputs carrying no `value` attributes:
+
+```html
+<div id="comment-section">
+  <ul>
+    <li><strong>Rosa: </strong>Lovely event — count me in for next year.</li>
+  </ul>
+  <form hx-post="/_components/comment_section/post" hx-target="#comment-section"
+        hx-swap="outerHTML" action="/_components/comment_section/post" method="post">
+    <div>
+      <label for="author">Name </label>
+      <input type="text" name="author" id="author"/>
+    </div>
+    <div>
+      <label for="body">Comment </label>
+      <input type="text" name="body" id="body"/>
+    </div>
+    <input type="submit" value="Add Comment"/>
+  </form>
+</div>
+```
+
+Typing a comment and submitting posts `author=Elena&body=See+you+there%21`, and the `200 OK` response is the same component with Elena's comment in the list — and the same valueless inputs as the initial render:
+
+```html
+  <ul>
+    <li><strong>Rosa: </strong>Lovely event — count me in for next year.</li>
+    <li><strong>Elena: </strong>See you there!</li>
+  </ul>
+  <form ...>
+```
+
+In a real browser the captured round trip reads the same: the POST body carries the typed values (`author=Browser%20Bot&body=Submitted%20by%20a%20real%20browser.`), and the post-swap DOM shows the new comment *and* empty inputs — the elements that held the typed text are gone, replaced by the response.
+
+## Related
+
+- [File Upload](file-upload.md) — clearing a param in the return for a different reason.
+- [Click to Edit](click-to-edit.md) — when you *do* want fields pre-filled, pair them with declared attributes.
+- [`performs`](../dsl.md#performs--user-initiated-actions) and [the callable contract](../dsl.md#the-callable-contract) in the DSL reference.

data/docs/examples/tabs.md

@@ -0,0 +1,102 @@
+# Tabs
+
+A row of tab buttons over a content panel. Clicking a tab fetches that tab's content from the server and swaps it into the panel — each tab is a component, and the server is the single source of truth for what's in it.
+
+This is Weft's take on [htmx's server-driven tabs example](https://htmx.org/examples/tabs-hateoas/). htmx's catalog also carries a second, JavaScript-flavored tabs variant for keeping tab state purely client-side; in Weft that fork in the road doesn't arise — components are server-rendered by design, so *this* pattern is the answer to both.
+
+## The components
+
+```ruby
+class DescriptionTab < Weft::Component
+  builder_method :description_tab
+  routable!
+
+  def build(attributes = {})
+    super
+    para "The Fairweather field kit packs a tarp, a stove, and a first-aid pouch " \
+         "into a single roll-top bag. Everything clips to the outside webbing."
+  end
+end
+
+class ShippingTab < Weft::Component
+  builder_method :shipping_tab
+  routable!
+
+  def build(attributes = {})
+    super
+    para "Orders placed before noon ship the same day. Standard delivery takes " \
+         "three to five business days; expedited arrives in two."
+  end
+end
+
+class ReturnsTab < Weft::Component
+  builder_method :returns_tab
+  routable!
+
+  def build(attributes = {})
+    super
+    para "Unused kits can be returned within thirty days for a full refund. " \
+         "Field-tested kits can be exchanged for store credit."
+  end
+end
+
+class ProductTabs < Weft::Component
+  builder_method :product_tabs
+
+  def build(attributes = {})
+    super
+    nav do
+      button "Description", tabs: DescriptionTab, target: "#product-tab-panel"
+      button "Shipping",    tabs: ShippingTab,    target: "#product-tab-panel"
+      button "Returns",     tabs: ReturnsTab,     target: "#product-tab-panel"
+    end
+    div id: "product-tab-panel" do
+      description_tab
+    end
+  end
+end
+```
+
+## How it works
+
+**Every button aims at the same panel.** [`tabs:`](../dsl.md#shorthands) presets trigger `:click` and swap `:fill`; the call site supplies the shared target. Clicking a tab fetches its component and replaces the panel's contents. The default tab is simply pre-rendered into the panel — the initial state is the same component a click would fetch.
+
+**`routable!` makes contentful-but-stateless tabs fetchable.** A component normally earns its route by declaring attributes or verbs ([Routing](../routing.md)); these tabs declare neither, so without help they would render fine *and* be unreachable over the wire — the buttons would point at URLs that 404. `routable!` opts them in explicitly. (Tabs that take wire state — an `order_id`, say — get their routes the ordinary way and don't need it.)
+
+**The selected tab isn't highlighted — yet.** Only the panel is swapped; the buttons themselves never re-render, so nothing moves a "selected" class around. htmx's example re-renders the whole tab bar with each click for exactly this reason. The Weft equivalent of that move is to give the wrapping component the state and re-render it whole — `attribute :tab` plus [`navigate: { tab: "shipping" }`](../dsl.md#navigate) on each button replaces the entire `ProductTabs` component, selected styling included, at the cost of re-sending the bar with every switch. Start with the version above; reach for `navigate:` when the highlight matters.
+
+## On the wire
+
+The initial render — three wired buttons, and the panel holding the default tab:
+
+```html
+<div id="product-tabs">
+  <nav>
+    <button hx-get="/_components/description_tab" hx-swap="innerHTML"
+            hx-target="#product-tab-panel" hx-trigger="click">Description</button>
+    <button hx-get="/_components/shipping_tab" hx-swap="innerHTML"
+            hx-target="#product-tab-panel" hx-trigger="click">Shipping</button>
+    <button hx-get="/_components/returns_tab" hx-swap="innerHTML"
+            hx-target="#product-tab-panel" hx-trigger="click">Returns</button>
+  </nav>
+  <div id="product-tab-panel">
+    <div id="description-tab">
+      <p>The Fairweather field kit packs a tarp, a stove, and a first-aid pouch into a single roll-top bag. Everything clips to the outside webbing.</p>
+    </div>
+  </div>
+</div>
+```
+
+Clicking Shipping issues `GET /_components/shipping_tab`, and the response fills the panel:
+
+```html
+<div id="shipping-tab">
+  <p>Orders placed before noon ship the same day. Standard delivery takes three to five business days; expedited arrives in two.</p>
+</div>
+```
+
+## Related
+
+- [Active Search](active-search.md) — the same fill-a-stable-container shape, driven by typing instead of clicks.
+- [`abstract!` and `routable!`](../routing.md#abstract-and-routable) in the routing reference.
+- The [shorthands table](../dsl.md#shorthands) in the DSL reference.