weft 0.1.0

data/docs/examples/active-search.md

@@ -0,0 +1,125 @@
+# Active Search
+
+A search box that filters a result list as the user types. Each (debounced) keystroke asks the server for matches, and the results region is refilled with the answer — search-as-you-type with all the logic living server-side.
+
+This is Weft's take on [htmx's active-search example](https://htmx.org/examples/active-search/), searching the same kind of small contact directory by name or email. One preset detail differs and is worth stating precisely: Weft's `live_search:` shorthand fires on `input changed delay:300ms` — the `input` event, debounced by 300 milliseconds — where htmx's published example uses `keyup changed delay:500ms`. If you want htmx's exact timing (or any other), the `trigger:` kwarg overrides the preset, as shown below.
+
+## The components
+
+```ruby
+PEOPLE = [
+  { name: "Venus Grimes",    email: "vgrimes@example.org" },
+  { name: "Kandy Kane",      email: "kandy@example.org" },
+  { name: "Antonia Benitez", email: "abenitez@example.org" },
+  { name: "Dewayne Sharp",   email: "dsharp@example.org" },
+  { name: "Nathan Grimes",   email: "ngrimes@example.org" },
+  { name: "Mia Chandler",    email: "mchandler@example.org" },
+  { name: "Leland Ortega",   email: "lortega@example.org" },
+  { name: "Saanvi Rao",      email: "srao@example.org" }
+].freeze
+
+class ContactResults < Weft::Component
+  builder_method :contact_results
+
+  attribute :q, default: ""
+
+  def build(attributes = {})
+    super
+    matches = search(attrs.q)
+    if matches.empty?
+      para "No one matches “#{attrs.q}”."
+    else
+      table do
+        thead { tr { th "Name"; th "Email" } }
+        tbody do
+          matches.each { |person| tr { td person[:name]; td person[:email] } }
+        end
+      end
+    end
+  end
+
+  private
+
+  def search(query)
+    q = query.strip.downcase
+    PEOPLE.select { |person| "#{person[:name]} #{person[:email]}".downcase.include?(q) }
+  end
+end
+
+class ContactSearch < Weft::Component
+  builder_method :contact_search
+
+  def build(attributes = {})
+    super
+    h3 "Search the directory"
+    input type: "search", name: "q", placeholder: "Begin typing to search...",
+          live_search: ContactResults, target: "#search-results"
+    div id: "search-results" do
+      contact_results(q: "")
+    end
+  end
+end
+```
+
+(The `PEOPLE` array stands in for your data layer — in a real app, `search` becomes a scoped query.)
+
+## How it works
+
+**The input's `name` is the search parameter.** [`live_search:`](../dsl.md#shorthands) presets trigger `:input` and swap `:fill`; the call site supplies the target. Notice that the generated URL below carries no query string — htmx includes the triggering input's own `name`/value with the request, which is how the typed text travels. The two halves must agree: the input says `name: "q"`, and `ContactResults` declares `attribute :q` to receive it. An empty default keeps the blank-box case (matching everyone) working.
+
+**Debounced by the preset, adjustable at the call site.** The `:input` semantic trigger expands to `input changed delay:300ms`: fire on input events, only when the value actually changed, at most once per 300ms lull. To reproduce htmx's example exactly, override it in place — the preset's request, swap, and target are all kept:
+
+```ruby
+input type: "search", name: "q",
+      live_search: ContactResults, target: "#search-results",
+      trigger: "keyup changed delay:500ms"
+```
+
+**Results refill a stable container.** The `:fill` swap replaces the *contents* of `#search-results`, so the container div persists across searches while a fresh `ContactResults` lands inside it each time. Pre-rendering `contact_results(q: "")` in the container means the page starts with the full directory rather than an empty pane — the initial state and every subsequent state are the same component.
+
+**The whole result set re-renders per search.** No row diffing, no client-side state: each request returns the complete table (or the "no matches" paragraph) for that query. At search-box scale this is the simple, correct trade.
+
+## On the wire
+
+The initial render — the wired input, and the container holding the unfiltered component:
+
+```html
+<input type="search" name="q" placeholder="Begin typing to search..."
+       hx-get="/_components/contact_results" hx-swap="innerHTML"
+       hx-target="#search-results" hx-trigger="input changed delay:300ms"/>
+<div id="search-results">
+  <div id="contact-results-">
+    <table>…all eight people…</table>
+  </div>
+</div>
+```
+
+(That `id="contact-results-"` is the component's DOM id — dasherized class name plus first attribute value, which here is the empty string.)
+
+Typing "grimes" settles into `GET /_components/contact_results?q=grimes`:
+
+```html
+<div id="contact-results-grimes">
+  <table>
+    <thead><tr><th>Name</th><th>Email</th></tr></thead>
+    <tbody>
+      <tr><td>Venus Grimes</td><td>vgrimes@example.org</td></tr>
+      <tr><td>Nathan Grimes</td><td>ngrimes@example.org</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+
+And a query with no matches (`GET /_components/contact_results?q=zz`) returns the friendly empty state:
+
+```html
+<div id="contact-results-zz">
+  <p>No one matches “zz”.</p>
+</div>
+```
+
+## Related
+
+- [Tabs](tabs.md) — the same fill-a-stable-container shape, driven by clicks instead of keystrokes.
+- The [shorthands table](../dsl.md#shorthands) and [trigger values](../dsl.md#trigger-values) in the DSL reference.
+- The [tutorial](../tutorial.md) covers the pairing of form field names with declared attributes in depth.

data/docs/examples/browser-dialogs.md

@@ -0,0 +1,71 @@
+# Browser Dialogs
+
+A destructive button guarded by the browser's native `confirm()` dialog — the user gets a chance to back out before the request is ever made, with no dialog component to build and no CSS to write.
+
+This is Weft's take on [htmx's dialogs example](https://htmx.org/examples/dialogs/). The honest point of this page is that Weft has no kwarg for `hx-confirm` — and doesn't need one: raw htmx attributes pass through to the element untouched, side by side with whatever the Weft kwargs expand to.
+
+## The components
+
+```ruby
+ACCOUNT = { status: "active" }
+
+class AccountPanel < Weft::Component
+  builder_method :account_panel
+
+  performs :deactivate do
+    ACCOUNT[:status] = "deactivated"
+    nil
+  end
+
+  def build(attributes = {})
+    super
+    para "Your account is #{ACCOUNT[:status]}."
+    if ACCOUNT[:status] == "active"
+      button "Deactivate my account", action: :deactivate,
+             "hx-confirm" => "Deactivate your account? You can sign back in to reactivate."
+    end
+  end
+end
+```
+
+(The `ACCOUNT` hash stands in for your data layer, and the current user for whoever your app has signed in.)
+
+## How it works
+
+**Raw htmx attributes ride along.** Weft intercepts only its own kwargs — `action:`, `trigger:`, and friends. Everything else on an element, string-keyed htmx attributes included, renders as a plain HTML attribute. So `"hx-confirm" => "..."` lands verbatim next to the wiring that [`action:`](../dsl.md#action) expanded, and htmx picks it up like any hand-written page. This is the general escape hatch: whenever htmx has a feature Weft has no vocabulary for, write the attribute yourself.
+
+**The guard lives in the browser, not on the server.** `hx-confirm` gates the *request*: htmx shows the native dialog and only issues the POST if the user accepts. The endpoint itself is unchanged — a request made outside htmx skips the question entirely. Treat it as protection against misclicks, never as access control; anything truly destructive still needs authorization server-side.
+
+**The action is ordinary Weft.** `performs :deactivate` runs the write and re-renders the component, which now shows the deactivated state — the standard action contract, unaware that a dialog ever happened.
+
+**`hx-prompt` doesn't carry over.** htmx's companion attribute asks for a line of text and sends the answer as an `HX-Prompt` *request header* — but a Weft action callable receives only the component's resolved attributes, which come from request parameters, so the prompted value never reaches your code. When an action needs user input, give the component a real input: a form field paired with a declared attribute, as in [Click to Edit](click-to-edit.md).
+
+## On the wire
+
+The initial render — the confirm attribute sits verbatim beside the expanded action wiring:
+
+```html
+<div id="account-panel">
+  <p>Your account is active.</p>
+  <button hx-confirm="Deactivate your account? You can sign back in to reactivate."
+          hx-post="/_components/account_panel/deactivate"
+          hx-target="#account-panel" hx-swap="outerHTML"
+          hx-vals="{}">Deactivate my account</button>
+</div>
+```
+
+Accepting the dialog issues `POST /_components/account_panel/deactivate`, and the re-rendered panel replaces the old one:
+
+```html
+<div id="account-panel">
+  <p>Your account is deactivated.</p>
+</div>
+```
+
+The same POST sent from outside the browser — no htmx, no dialog — is accepted just the same, which is exactly why the confirm is a courtesy and the authorization is your job.
+
+## Related
+
+- [Modal Dialog](modal-dialog.md) — when you want a dialog you own instead of the browser's.
+- [Click to Edit](click-to-edit.md) — form fields paired with attributes: the Weft answer to "prompt the user for a value."
+- [`action:`](../dsl.md#action) and [`performs`](../dsl.md#performs--user-initiated-actions) in the DSL reference.

data/docs/examples/bulk-update.md

@@ -0,0 +1,122 @@
+# Bulk Update
+
+A table of team members, each row with an Activate checkbox; one submit applies every change at once, and a status line reports how many members were activated and deactivated.
+
+This is Weft's take on [htmx's bulk-update example](https://htmx.org/examples/bulk-update/), with one structural difference. Their form posts the checkboxes and swaps a toast message into a separate slot, leaving the table as the user left it; in Weft the whole roster is one component, so the submit re-renders it from server state — the checkboxes come back showing what was actually saved, with the status line beneath them.
+
+## The components
+
+```ruby
+TEAM_MEMBERS = {
+  "1" => { name: "Joe Smith",       email: "joe@smith.org",       active: true },
+  "2" => { name: "Angie MacDowell", email: "angie@macdowell.org", active: true },
+  "3" => { name: "Fuqua Tarkenton", email: "fuqua@tarkenton.org", active: true },
+  "4" => { name: "Kim Yee",         email: "kim@yee.org",         active: false }
+}.freeze
+
+class MemberRoster < Weft::Component
+  builder_method :member_roster
+
+  attribute :active_ids, default: []
+  attribute :status
+
+  performs :update, target: "#member-roster" do |attrs|
+    checked = attrs.active_ids
+    activated = deactivated = 0
+    TEAM_MEMBERS.each do |id, member|
+      active = checked.include?(id)
+      activated += 1 if active && !member[:active]
+      deactivated += 1 if !active && member[:active]
+      member[:active] = active
+    end
+    { status: "Activated #{activated} and deactivated #{deactivated} members." }
+  end
+
+  def build(attributes = {})
+    super
+    set_attribute :id, "member-roster"
+    form(action: :update) do
+      table do
+        thead { tr { th "Name"; th "Email"; th "Active" } }
+        tbody do
+          TEAM_MEMBERS.each do |id, member|
+            tr do
+              td member[:name]
+              td member[:email]
+              td do
+                if member[:active]
+                  input type: "checkbox", name: "active_ids[]", value: id, checked: "checked"
+                else
+                  input type: "checkbox", name: "active_ids[]", value: id
+                end
+              end
+            end
+          end
+        end
+      end
+      input type: "submit", value: "Bulk Update"
+    end
+    para attrs.status if attrs.status
+  end
+end
+```
+
+(The `TEAM_MEMBERS` hash stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**Bracket naming turns the checkboxes into one array.** Every checkbox shares the name `active_ids[]`, and Rack's parameter parsing folds those into a single array under the bracket-less key — so the component's declared `active_ids` attribute receives `["1", "2", "4"]`, and the callable reads it as `attrs.active_ids`. The values arrive as strings, which is why the data stub's keys are strings too. Checkboxes the user leaves unchecked simply aren't in the submission; that's the whole trick of the pattern.
+
+**The `default: []` is load-bearing.** When *no* boxes are checked, the browser sends no `active_ids` parameter at all, and the attribute falls back to its default. An empty array makes that case mean "deactivate everyone" — and guarantees the callable always has a real array to call `include?` on, rather than `nil`.
+
+**The callable diffs, then reports through its return value.** It compares each member's stored state against the submitted array, counts the flips, and writes the new state. Returning a hash merges it into the attrs for the re-render (see [the callable contract](../dsl.md#the-callable-contract)), so `{ status: "Activated 1 and deactivated 1 members." }` is how the count reaches the status line — `attrs.status` is `nil` on a fresh render and the paragraph only appears after an update.
+
+**An array can't anchor a DOM id.** Weft derives a component's DOM id from its first declared attribute — perfect when that's a record id, unusable when it's an array (`id="member-roster-[]"` is not a selector htmx can target). So this component pins its own identity: `set_attribute :id, "member-roster"` fixes the wrapper's id inside `build`, and `performs :update, target: "#member-roster"` points the action's swap at that same anchor. Both live server-side, so every re-rendered fragment carries the same stable wiring.
+
+**The checkboxes tell the truth after the write.** `build` renders each checkbox from the data store, not from the submitted attrs — the response reflects what was actually saved. And since `form(action: :update)` also emits plain `action`/`method` attributes, the whole thing degrades to a normal POST without JavaScript.
+
+## On the wire
+
+The initial render (or `GET /_components/member_roster`) — the form wired to the action, one row per member:
+
+```html
+<div id="member-roster">
+  <form hx-post="/_components/member_roster/update" hx-target="#member-roster"
+        hx-swap="outerHTML" action="/_components/member_roster/update" method="post">
+    <table>
+      <thead>...</thead>
+      <tbody>
+        <tr>
+          <td>Joe Smith</td>
+          <td>joe@smith.org</td>
+          <td><input type="checkbox" name="active_ids[]" value="1" checked="checked"/></td>
+        </tr>
+        ...
+        <tr>
+          <td>Kim Yee</td>
+          <td>kim@yee.org</td>
+          <td><input type="checkbox" name="active_ids[]" value="4"/></td>
+        </tr>
+      </tbody>
+    </table>
+    <input type="submit" value="Bulk Update"/>
+  </form>
+</div>
+```
+
+Unchecking Fuqua, checking Kim, and submitting sends `POST /_components/member_roster/update` with the body `active_ids[]=1&active_ids[]=2&active_ids[]=4`. The response is the same component, re-rendered from the updated store — Fuqua's box now unchecked, Kim's checked — ending with:
+
+```html
+    <input type="submit" value="Bulk Update"/>
+  </form>
+  <p>Activated 1 and deactivated 1 members.</p>
+</div>
+```
+
+Submitting with every box unchecked sends an empty body; the default kicks in and the response reports `Activated 0 and deactivated 3 members.`
+
+## Related
+
+- [Click to Edit](click-to-edit.md) — the basics of pairing form fields with declared attributes.
+- [Delete Row](delete-row.md) and [Edit Row](edit-row.md) — acting on table rows one at a time instead of all at once.
+- [`performs`](../dsl.md#performs--user-initiated-actions) and [the callable contract](../dsl.md#the-callable-contract) in the DSL reference.

data/docs/examples/click-to-edit.md

@@ -0,0 +1,113 @@
+# Click to Edit
+
+A read-only view of a record with an Edit button. Clicking swaps an editable form into its place; saving — or canceling — swaps the read-only view back. No page navigation, and no JavaScript beyond what Weft already ships.
+
+This is Weft's take on [htmx's click-to-edit example](https://htmx.org/examples/click-to-edit/), and the shape is the same: the UI moves between two states, and each state is a server-rendered fragment. In Weft, each state is simply a component.
+
+## The components
+
+```ruby
+CONTACTS = {
+  "1" => { first_name: "Joe", last_name: "Blow", email: "joe@blow.com" }
+}.freeze
+
+class ContactCard < Weft::Component
+  builder_method :contact_card
+
+  attribute :contact_id
+
+  def build(attributes = {})
+    super
+    contact = CONTACTS.fetch(attrs.contact_id)
+    div { strong "First Name: "; text_node contact[:first_name] }
+    div { strong "Last Name: ";  text_node contact[:last_name] }
+    div { strong "Email: ";      text_node contact[:email] }
+    button "Click To Edit",
+           loads: ContactEditor, with: { contact_id: attrs.contact_id },
+           swap: :replace, target: self
+  end
+end
+
+class ContactEditor < Weft::Component
+  builder_method :contact_editor
+
+  attribute :contact_id
+  attribute :first_name
+  attribute :last_name
+  attribute :email
+
+  transfers :save, to: ContactCard do |attrs|
+    CONTACTS.fetch(attrs.contact_id).merge!(
+      first_name: attrs.first_name, last_name: attrs.last_name, email: attrs.email
+    )
+    nil
+  end
+
+  def build(attributes = {})
+    super
+    contact = CONTACTS.fetch(attrs.contact_id)
+    form(action: :save) do
+      input(type: "hidden", name: "contact_id", value: attrs.contact_id)
+      div do
+        label("First Name ", for: "first_name")
+        input(type: "text", name: "first_name", id: "first_name", value: contact[:first_name])
+      end
+      div do
+        label("Last Name ", for: "last_name")
+        input(type: "text", name: "last_name", id: "last_name", value: contact[:last_name])
+      end
+      div do
+        label("Email ", for: "email")
+        input(type: "text", name: "email", id: "email", value: contact[:email])
+      end
+      input(type: "submit", value: "Submit")
+      button "Cancel", type: "button",
+             loads: ContactCard, with: { contact_id: attrs.contact_id },
+             swap: :replace, target: self
+    end
+  end
+end
+```
+
+(The `CONTACTS` hash stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**Reads and writes get different verbs.** Opening the editor changes nothing on the server, so the Edit button is a [`loads:`](../dsl.md#loads) — a plain GET that fetches the editor component and swaps it over the card (`swap: :replace`). Cancel is the same thing pointed back at the card. Saving *does* change something, so it's a [`transfers`](../dsl.md#transfers--actions-that-render-something-else): a POST that runs the write, then renders the card — the natural "what you see after saving" — in the editor's place.
+
+**`target: self` pins the swap to the component.** Inside `build`, `self` is the component instance, and a component reference as a `target:` resolves to its DOM id. Each fragment replaces the whole card/editor element, wherever it sits in the page.
+
+**The two components reference each other — without a cycle.** `transfers :save, to: ContactCard` runs in the class body, so `ContactCard` must already be defined; but `loads: ContactEditor` isn't evaluated until render. Defining the display component first therefore breaks the loop with no forward-declaration tricks. This ordering trick generalizes to any two-state component pair.
+
+**Form fields pair with declared attributes.** The editor declares `first_name`, `last_name`, and `email` so its fields reach the save callable as `attrs.first_name` and friends — and `contact_id` rides along as a hidden input, because it's part of the component's identity rather than something the user edits. (This pairing is covered in depth in [the tutorial](../tutorial.md#7-taking-rsvps).)
+
+**It still works without JavaScript.** `form(action: :save)` emits plain `action`/`method` attributes alongside the htmx wiring, so the save degrades to a normal POST. Note `type: "button"` on Cancel — inside a form, a bare `<button>` is a submit button.
+
+## On the wire
+
+The initial render (or `GET /_components/contact_card?contact_id=1`):
+
+```html
+<div id="contact-card-1">
+  <div><strong>First Name: </strong>Joe</div>
+  <div><strong>Last Name: </strong>Blow</div>
+  <div><strong>Email: </strong>joe@blow.com</div>
+  <button hx-get="/_components/contact_editor?contact_id=1"
+          hx-swap="outerHTML" hx-target="#contact-card-1">Click To Edit</button>
+</div>
+```
+
+Clicking Edit fetches the editor; its form is wired to the save action, with the non-JS fallback visible:
+
+```html
+<form hx-post="/_components/contact_editor/save" hx-target="#contact-editor-1"
+      hx-swap="outerHTML" action="/_components/contact_editor/save" method="post">
+```
+
+Submitting `POST /_components/contact_editor/save` with the edited fields returns the updated card — `<div id="contact-card-1">…Joseph…</div>` — which replaces the editor. The next fetch of the card confirms the write stuck.
+
+## Related
+
+- [Edit Row](edit-row.md) — this same pattern applied per-row in a table.
+- [`loads:`](../dsl.md#loads) and [`transfers`](../dsl.md#transfers--actions-that-render-something-else) in the DSL reference.
+- htmx's original uses a RESTful `PUT`; if you prefer that, `transfers :save, to: ContactCard, method: :put` does exactly what you'd hope.

data/docs/examples/click-to-load.md

@@ -0,0 +1,77 @@
+# Click to Load
+
+A list that shows its first page up front, with a "load more" button at the bottom. Clicking the button replaces it with the next page of results — which brings its own button, until the data runs out. The page never reloads, and nothing already on screen is disturbed.
+
+This is Weft's take on [htmx's click-to-load example](https://htmx.org/examples/click-to-load/), with the same cast of agents. One structural difference is worth knowing up front: htmx's version returns a loose fragment of sibling `<tr>`s to splice into a table, but a Weft component always renders exactly one wrapper element. So the Weft shape is a *chunk* — one element holding a page of results plus the next button — and each chunk lands where the previous button was. (For tables specifically, see [Infinite Scroll](infinite-scroll.md), whose append-style swap plays naturally with `<tbody>` chunks.)
+
+## The components
+
+```ruby
+AGENTS = (1..24).map { |n| { name: "Agent Smith", email: "void#{n}@null.org", number: n } }.freeze
+
+class AgentRows < Weft::Component
+  builder_method :agent_rows
+
+  PER_PAGE = 6
+
+  attribute :page, default: 1
+
+  def build(attributes = {})
+    super
+    batch = AGENTS[(attrs.page - 1) * PER_PAGE, PER_PAGE]
+    batch.each do |agent|
+      div { strong agent[:name]; text_node " — #{agent[:email]} (##{agent[:number]})" }
+    end
+    if attrs.page * PER_PAGE < AGENTS.size
+      button "Load More Agents...", load_more: AgentRows, with: { page: attrs.page + 1 }
+    end
+  end
+end
+```
+
+(The `AGENTS` array stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+Render `agent_rows(page: 1)` wherever the list lives, and the pattern takes care of itself from there.
+
+## How it works
+
+**One shorthand, no ceremony.** [`load_more:`](../dsl.md#shorthands) is a preset over the [`loads:`](../dsl.md#loads) machinery: trigger `:click`, swap `:replace`, target `:self`. In plain terms — when this button is clicked, fetch the named component and put it where the button was. The call site supplies only what varies: which component to load (`AgentRows`, the component's own class) and its wire attrs (`with: { page: attrs.page + 1 }`).
+
+**The component is a chunk, not the whole list.** Each `AgentRows` instance renders one page of agents and, when more remain, the button that fetches the next chunk *in its own place*. Clicking never touches the agents already on screen; the button alone is replaced, and the new chunk arrives with its own button. The recursion bottoms out naturally — the `if` guard means the final chunk simply renders no button.
+
+**Attributes make the chunk addressable.** Declaring `attribute :page, default: 1` gives the component a route ([Routing](../routing.md)) and coerces the wire value: `page=2` arrives as the string `"2"` and reaches `attrs.page` as the Integer `2`, because the default is an Integer.
+
+**A component can load itself.** `load_more: AgentRows` inside `AgentRows`'s own `build` is unremarkable — the class reference is evaluated at render time, so self-reference needs no tricks.
+
+## On the wire
+
+The initial render (or `GET /_components/agent_rows?page=1`):
+
+```html
+<div id="agent-rows-1">
+  <div><strong>Agent Smith</strong> — void1@null.org (#1)</div>
+  <!-- … five more agents … -->
+  <button hx-get="/_components/agent_rows?page=2" hx-swap="outerHTML"
+          hx-target="this" hx-trigger="click">Load More Agents...</button>
+</div>
+```
+
+Every htmx attribute there came from the one `load_more:` kwarg. Clicking issues `GET /_components/agent_rows?page=2`, and the response replaces the button:
+
+```html
+<div id="agent-rows-2">
+  <div><strong>Agent Smith</strong> — void7@null.org (#7)</div>
+  <!-- … -->
+  <button hx-get="/_components/agent_rows?page=3" hx-swap="outerHTML"
+          hx-target="this" hx-trigger="click">Load More Agents...</button>
+</div>
+```
+
+The last page (`GET /_components/agent_rows?page=4`) renders its agents and no button — the interaction retires itself.
+
+## Related
+
+- [Infinite Scroll](infinite-scroll.md) — the same next-page mechanic, triggered by scrolling instead of a click, in a real table.
+- [Lazy Loading](lazy-loading.md) — deferring one expensive section rather than paginating many.
+- The [shorthands table](../dsl.md#shorthands) in the DSL reference, including how to register your own preset.
+- For pagination that *replaces* the current page instead of accumulating, [`navigate:`](../dsl.md#navigate) is the better verb.

data/docs/examples/delete-row.md

@@ -0,0 +1,101 @@
+# Delete Row
+
+A table of contacts, each row with a Delete button. Clicking it asks the browser's native "Are you sure?", deletes the record on the server, and removes the row from the table.
+
+This is Weft's take on [htmx's delete-row example](https://htmx.org/examples/delete-row/). Their version hoists the htmx attributes onto the `<tbody>` and lets every row inherit them; a Weft row is a component that carries its own wiring, generated from its own declaration. One cosmetic difference: htmx's original fades the row out over a second before removing it — that's a CSS transition plus a swap delay, and their approach carries over unchanged if you want it. This version keeps zero CSS and removes the row immediately.
+
+## The components
+
+```ruby
+CONTACT_BOOK = {
+  "1" => { name: "Angie MacDowell", email: "angie@macdowell.org", status: "Active" },
+  "2" => { name: "Fuqua Tarkenton", email: "fuqua@tarkenton.org", status: "Active" },
+  "3" => { name: "Kim Yee",         email: "kim@yee.org",         status: "Inactive" }
+}
+
+class ContactRow < Weft::Component
+  builder_method :contact_row
+
+  attribute :contact_id
+
+  dismisses :destroy do |attrs|
+    CONTACT_BOOK.delete(attrs.contact_id)
+    nil
+  end
+
+  def tag_name
+    "tr"
+  end
+
+  def build(attributes = {})
+    super
+    contact = CONTACT_BOOK[attrs.contact_id]
+    return unless contact
+
+    td contact[:name]
+    td contact[:email]
+    td contact[:status]
+    td do
+      button "Delete", action: :destroy, "hx-confirm" => "Are you sure?"
+    end
+  end
+end
+
+class ContactsTable < Weft::Component
+  builder_method :contacts_table
+
+  def build(attributes = {})
+    super
+    table do
+      thead { tr { th "Name"; th "Email"; th "Status"; th "" } }
+      tbody do
+        CONTACT_BOOK.each_key { |id| contact_row(contact_id: id) }
+      end
+    end
+  end
+end
+```
+
+(The `CONTACT_BOOK` hash stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**The row is the component.** Overriding `tag_name` makes the wrapper a `<tr>`, so each contact renders as a real table row with its own DOM id. The identifying attribute is declared first because that's where the id comes from — `contact_id` of `"1"` yields `id="contact-row-1"`, which is exactly what the delete needs to target.
+
+**`dismisses` is the delete-shaped verb.** It's sugar for a `performs` with `method: :delete, swap: :delete` (see [`dismisses`](../dsl.md#dismisses--remove-from-the-dom)): the button wired with `action: :destroy` issues a `DELETE` to the action's route, the callable removes the record, and on success htmx deletes the target element — the row — from the DOM. The row's identity travels automatically: an action button carries the component's attrs as `hx-vals`. Note there's no non-JavaScript fallback here — plain HTML has no DELETE — which is the nature of the pattern rather than a Weft limitation.
+
+**The confirmation is one raw attribute.** Kwargs Weft doesn't recognize pass straight through to the element, so `"hx-confirm" => "Are you sure?"` lands on the button as-is and htmx shows the browser's native confirm dialog before sending anything. No request fires on Cancel. For the fuller confirm-and-prompt story, see [Browser Dialogs](browser-dialogs.md).
+
+**The dismissal response is rendered, then thrown away.** htmx ignores the response body on a delete swap, but Weft still renders the component once after the callable runs — so `build` must survive the record being gone, hence the `return unless contact` guard (an empty `<tr>` nobody will see). The trailing `nil` in the callable matters for the same reason: `Hash#delete` returns the deleted record, and a hash returned from a callable merges into the attrs for that final render. If the callable *raises*, Weft overrides the destructive swap (via `HX-Reswap`) so the error rendering appears where the row was, instead of the row silently vanishing.
+
+## On the wire
+
+Each row arrives fully wired — `GET /_components/contact_row?contact_id=1` returns the same fragment the table renders inline:
+
+```html
+<tr id="contact-row-1">
+  <td>Angie MacDowell</td>
+  <td>angie@macdowell.org</td>
+  <td>Active</td>
+  <td>
+    <button hx-confirm="Are you sure?" hx-delete="/_components/contact_row/destroy"
+            hx-target="#contact-row-1" hx-swap="delete"
+            hx-vals="{&quot;contact_id&quot;:&quot;1&quot;}">Delete</button>
+  </td>
+</tr>
+```
+
+Confirming the dialog sends `DELETE /_components/contact_row/destroy?contact_id=1` (htmx 2 puts DELETE parameters in the query string). The server deletes the record and responds `200` with the guarded, now-empty render — which htmx discards while removing the row:
+
+```html
+<tr id="contact-row-1"></tr>
+```
+
+Fetching the table again shows two rows; fetching the deleted row's own URL returns the same empty `<tr>`, confirming the record is gone.
+
+## Related
+
+- [Browser Dialogs](browser-dialogs.md) — the confirm/prompt story in full.
+- [Edit Row](edit-row.md) — rows that switch into an editable state instead of disappearing.
+- [Inline Expansion](inline-expansion.md) — another `tag_name "tr"` component, inserted rather than removed.
+- [`dismisses`](../dsl.md#dismisses--remove-from-the-dom) in the DSL reference.