weft 0.1.0

data/docs/examples/edit-row.md

@@ -0,0 +1,146 @@
+# Edit Row
+
+A table where each row can switch into an editable state: Edit swaps the row for a row of inputs, Save writes the changes and swaps the display row back, Cancel backs out without saving.
+
+This is Weft's take on [htmx's edit-row example](https://htmx.org/examples/edit-row/) — the [click-to-edit](click-to-edit.md) pattern applied per row. Two honest differences: their version uses hyperscript to enforce editing one row at a time, while here each row is its own independent component pair — several rows can be in edit mode at once, and one-at-a-time is app policy this example doesn't impose. And where their editor gathers its inputs with `hx-include="closest tr"`, this version leans on plain HTML instead.
+
+## The components
+
+```ruby
+PEOPLE = {
+  "1" => { name: "Joe Smith",       email: "joe@smith.org" },
+  "2" => { name: "Angie MacDowell", email: "angie@macdowell.org" },
+  "3" => { name: "Fuqua Tarkenton", email: "fuqua@tarkenton.org" }
+}.freeze
+
+class PersonRow < Weft::Component
+  builder_method :person_row
+
+  attribute :person_id
+
+  def tag_name
+    "tr"
+  end
+
+  def build(attributes = {})
+    super
+    person = PEOPLE.fetch(attrs.person_id)
+    td person[:name]
+    td person[:email]
+    td do
+      button "Edit", loads: PersonRowEditor, with: { person_id: attrs.person_id },
+                     swap: :replace, target: self
+    end
+  end
+end
+
+class PersonRowEditor < Weft::Component
+  builder_method :person_row_editor
+
+  attribute :person_id
+  attribute :name
+  attribute :email
+
+  transfers :save, to: PersonRow do |attrs|
+    PEOPLE.fetch(attrs.person_id).merge!(name: attrs.name, email: attrs.email)
+    nil
+  end
+
+  def tag_name
+    "tr"
+  end
+
+  def build(attributes = {})
+    super
+    person = PEOPLE.fetch(attrs.person_id)
+    save_form = "save-person-#{attrs.person_id}"
+    td { input type: "text", name: "name", value: person[:name], form: save_form }
+    td { input type: "text", name: "email", value: person[:email], form: save_form }
+    td do
+      form(action: :save, id: save_form) do
+        input type: "hidden", name: "person_id", value: attrs.person_id
+        input type: "submit", value: "Save"
+        button "Cancel", type: "button",
+               loads: PersonRow, with: { person_id: attrs.person_id },
+               swap: :replace, target: self
+      end
+    end
+  end
+end
+
+class PeopleTable < Weft::Component
+  builder_method :people_table
+
+  def build(attributes = {})
+    super
+    table do
+      thead { tr { th "Name"; th "Email"; th "" } }
+      tbody do
+        PEOPLE.each_key { |id| person_row(person_id: id) }
+      end
+    end
+  end
+end
+```
+
+(The `PEOPLE` hash stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**It's click-to-edit, once per row.** Both components render as `<tr>` (the `tag_name` override), with the identifying attribute declared first so each carries a usable DOM id. Entering edit mode changes nothing on the server, so Edit is a [`loads:`](../dsl.md#loads) — a GET that fetches the editor row and replaces the display row (`swap: :replace, target: self`). Saving is a [`transfers`](../dsl.md#transfers--actions-that-render-something-else): the write runs, then the *display* row renders in the editor's place. Cancel is the Edit button's mirror image, pointed back at `PersonRow`. As in click-to-edit, defining the display component first lets `transfers :save, to: PersonRow` resolve in the editor's class body, while `loads: PersonRowEditor` waits until render.
+
+**A form can't wrap table cells — so the cells point at the form.** HTML won't allow a `<form>` to span `<td>`s inside a row, which is the structural puzzle of this pattern. htmx's original solves it with `hx-include="closest tr"`; here plain HTML does the same job: the form lives in the last cell, and the name and email inputs associate with it from their own cells via the standard [`form` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#form). Form-associated elements are part of the form's submission set, so both htmx's payload *and* the no-JavaScript fallback submission include all three fields — nothing about the association needs scripting.
+
+**Rows edit independently.** Each row is a self-contained component pair with its own ids (`person-row-2`, `person-row-editor-2`, `save-person-2`), so opening one editor doesn't disturb another. If your app wants only one row editable at a time, that's a policy to enforce on top of this pattern, not something the components themselves impose.
+
+## On the wire
+
+Each display row arrives wired (`GET /_components/person_row?person_id=1` returns the same fragment the table renders):
+
+```html
+<tr id="person-row-1">
+  <td>Joe Smith</td>
+  <td>joe@smith.org</td>
+  <td>
+    <button hx-get="/_components/person_row_editor?person_id=1"
+            hx-swap="outerHTML" hx-target="#person-row-1">Edit</button>
+  </td>
+</tr>
+```
+
+Clicking Edit fetches the editor row — note the `form` attributes tying the scattered inputs to the form in the last cell, and the non-JS fallback on the form itself:
+
+```html
+<tr id="person-row-editor-1">
+  <td><input type="text" name="name" value="Joe Smith" form="save-person-1"/></td>
+  <td><input type="text" name="email" value="joe@smith.org" form="save-person-1"/></td>
+  <td>
+    <form id="save-person-1" hx-post="/_components/person_row_editor/save"
+          hx-target="#person-row-editor-1" hx-swap="outerHTML"
+          action="/_components/person_row_editor/save" method="post">
+      <input type="hidden" name="person_id" value="1"/>
+      <input type="submit" value="Save"/>
+      <button type="button" hx-get="/_components/person_row?person_id=1"
+              hx-swap="outerHTML" hx-target="#person-row-editor-1">Cancel</button>
+    </form>
+  </td>
+</tr>
+```
+
+Submitting `POST /_components/person_row_editor/save` with the edited fields returns the updated display row, which replaces the editor:
+
+```html
+<tr id="person-row-1">
+  <td>Joe B. Smith</td>
+  <td>joe.smith@example.com</td>
+  ...
+</tr>
+```
+
+Only the attributes `PersonRow` itself declares travel into that render — the editor's `name` and `email` were consumed by the save and play no part in the row's element.
+
+## Related
+
+- [Click to Edit](click-to-edit.md) — the same two-state pattern on a standalone card, where a form can simply wrap its fields.
+- [Delete Row](delete-row.md) — rows that leave the table instead of switching state.
+- [`loads:`](../dsl.md#loads) and [`transfers`](../dsl.md#transfers--actions-that-render-something-else) in the DSL reference.

data/docs/examples/file-upload.md

@@ -0,0 +1,96 @@
+# File Upload
+
+A file input, an Upload button, and a list of everything uploaded so far. The file travels through a component action like any other form submission, and the component re-renders with the list grown by one.
+
+This is Weft's take on [htmx's file-upload example](https://htmx.org/examples/file-upload/), covering the upload itself; their JavaScript-driven progress meter is out of scope here — that part is hand-written JS even in htmx's own catalog.
+
+## The components
+
+```ruby
+UPLOADED_REPORTS = []
+
+class ReportUploader < Weft::Component
+  builder_method :report_uploader
+
+  attribute :document
+
+  performs :upload do |attrs|
+    file = attrs.document
+    if file.is_a?(Hash) && file[:tempfile]
+      UPLOADED_REPORTS << { name: file[:filename], size: file[:tempfile].size }
+    end
+    { document: nil }
+  end
+
+  def build(attributes = {})
+    super
+    form(action: :upload, enctype: "multipart/form-data") do
+      input type: "file", name: "document"
+      input type: "submit", value: "Upload"
+    end
+    if UPLOADED_REPORTS.any?
+      h3 "Uploaded"
+      ul do
+        UPLOADED_REPORTS.each { |doc| li "#{doc[:name]} (#{doc[:size]} bytes)" }
+      end
+    end
+  end
+end
+```
+
+(The `UPLOADED_REPORTS` array stands in for wherever your app actually puts files — storage service, attachment library, what have you.)
+
+## How it works
+
+**One HTML attribute makes it multipart.** `enctype: "multipart/form-data"` isn't Weft vocabulary — it passes through to the `<form>` untouched, and it does double duty there: htmx honors a form's native enctype when it builds the request, and the no-JS fallback submit needs the same attribute anyway. Leave it off and the request still fires, but as an ordinary urlencoded POST whose file field has collapsed to the string `"[object File]"` — nothing a server can use. (htmx also has an `hx-encoding` attribute; it's only needed to force multipart from something other than a form.)
+
+**The file arrives through a declared attribute.** The `document` attribute receives whatever the server's multipart parsing produces — under Sinatra, a hash carrying `:filename`, `:type`, and a `:tempfile` ready to read. The callable checks for that shape before storing, which quietly covers the other case too: submitting with no file chosen sends `document=` (an empty string), the `is_a?(Hash)` guard skips it, and the re-render is a no-op.
+
+**Returning `{ document: nil }` is load-bearing.** A callable's returned hash merges into the attrs for the re-render ([the callable contract](../dsl.md#the-callable-contract)) — and this one uses that to *clear* the file param rather than add anything. Weft derives a component's DOM id from its first declared attribute, and a tempfile-toting multipart hash in that slot would smear itself across the wrapper's id and every piece of htmx wiring derived from it. Cleared, the component comes back as plain `#report-uploader`: same id, same wiring, fresh empty file input.
+
+## On the wire
+
+The initial render (or `GET /_components/report_uploader`) — the enctype sits as a plain HTML attribute beside the htmx wiring and the no-JS fallback:
+
+```html
+<div id="report-uploader">
+  <form enctype="multipart/form-data" hx-post="/_components/report_uploader/upload"
+        hx-target="#report-uploader" hx-swap="outerHTML"
+        action="/_components/report_uploader/upload" method="post">
+    <input type="file" name="document"/>
+    <input type="submit" value="Upload"/>
+  </form>
+</div>
+```
+
+Choosing a file and pressing Upload sends a genuine multipart body — this one captured from htmx in a browser:
+
+```
+POST /_components/report_uploader/upload
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundarySSp7J2ErxcZUwkP2
+
+------WebKitFormBoundarySSp7J2ErxcZUwkP2
+Content-Disposition: form-data; name="document"; filename="browser-note.txt"
+Content-Type: text/plain
+
+hello from a real browser
+------WebKitFormBoundarySSp7J2ErxcZUwkP2--
+```
+
+The response is the component re-rendered, upload duly listed:
+
+```html
+  <h3>Uploaded</h3>
+  <ul>
+    <li>browser-note.txt (25 bytes)</li>
+  </ul>
+</div>
+```
+
+The endpoint doesn't care where the multipart came from — a no-JS browser submit or `curl -F "document=@q3-report.txt" …` lands the same way. And the cautionary baseline: the identical browser submit *without* the enctype attribute arrives as `document=%5Bobject%20File%5D`, and nothing is stored.
+
+## Related
+
+- [Reset User Input](reset-user-input.md) — the same clear-it-in-the-return move, there to keep text fields empty.
+- [Inline Validation](inline-validation.md) — rejecting a bad submission with a `422` instead of quietly ignoring it.
+- [`performs`](../dsl.md#performs--user-initiated-actions) and [the callable contract](../dsl.md#the-callable-contract) in the DSL reference.

data/docs/examples/infinite-scroll.md

@@ -0,0 +1,98 @@
+# Infinite Scroll
+
+A table that grows as you read it: when the last visible row scrolls into view, the next page of rows is fetched and appended after it — no button, no page numbers, no end-of-page cliff until the data genuinely runs out.
+
+This is Weft's take on [htmx's infinite-scroll example](https://htmx.org/examples/infinite-scroll/), and the mechanism is the same: the final row of each batch carries a `revealed` trigger, and each response ends with the next trigger row. Where htmx's server returns a loose fragment of `<tr>`s, a Weft component renders one wrapper element — so here each batch is a `<tbody>`, appended as a sibling of the last. HTML happily allows a table multiple `<tbody>` elements, which makes it the natural chunk unit for growing tables.
+
+## The components
+
+```ruby
+DIRECTORY = (1..42).map { |n| { name: "Contact #{n}", email: "contact#{n}@example.org" } }.freeze
+
+class ContactRows < Weft::Component
+  builder_method :contact_rows
+
+  PER_PAGE = 10
+
+  attribute :page, default: 1
+
+  def tag_name
+    "tbody"
+  end
+
+  def build(attributes = {})
+    super
+    rows = DIRECTORY[(attrs.page - 1) * PER_PAGE, PER_PAGE]
+    rows.each_with_index do |contact, index|
+      if index == rows.size - 1 && more_pages?
+        tr(infinite_scroll: ContactRows, with: { page: attrs.page + 1 }, target: "closest tbody") do
+          td contact[:name]; td contact[:email]
+        end
+      else
+        tr { td contact[:name]; td contact[:email] }
+      end
+    end
+  end
+
+  private
+
+  def more_pages?
+    attrs.page * PER_PAGE < DIRECTORY.size
+  end
+end
+
+class ContactDirectory < Weft::Component
+  builder_method :contact_directory
+
+  def build(attributes = {})
+    super
+    h3 "Contact directory"
+    table do
+      thead { tr { th "Name"; th "Email" } }
+      contact_rows(page: 1)
+    end
+  end
+end
+```
+
+(The `DIRECTORY` array stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**The last row is the sentinel.** [`infinite_scroll:`](../dsl.md#shorthands) presets trigger `:visible` and swap `:after`; the call site adds the target. Placed on the final `tr` of a batch, it means: when this row scrolls into view, fetch the next batch and insert it after the closest `tbody`. The trigger expands to htmx's `revealed`, which fires once per element — each sentinel row does its job exactly one time.
+
+**`target: "closest tbody"` keeps the table valid.** The fetched component is a whole `<tbody>` (that's the `tag_name` override), and swapping it `afterend` of the *row* would nest table sections illegally. Aiming the swap at the closest `tbody` instead makes each batch a sibling section — the shape HTML already sanctions for row grouping. This is why the preset leaves the target to you: only the call site knows what the insertion point should be.
+
+**The chain stops itself.** The sentinel wiring is only rendered while `more_pages?` holds. The final batch is just rows — nothing left to trigger, nothing fetched past the end of the data.
+
+**`page` travels as wire state.** `attribute :page, default: 1` makes each batch independently addressable (`/_components/contact_rows?page=3`) and coerces the URL string to an Integer, since the default is one. The `ContactDirectory` wrapper, by contrast, declares nothing — it's plain composition and renders only as part of a page.
+
+## On the wire
+
+The initial render (or `GET /_components/contact_rows?page=1`) — nine plain rows, then the sentinel:
+
+```html
+<tbody id="contact-rows-1">
+  <tr><td>Contact 1</td><td>contact1@example.org</td></tr>
+  <!-- … -->
+  <tr hx-get="/_components/contact_rows?page=2" hx-swap="afterend"
+      hx-target="closest tbody" hx-trigger="revealed">
+    <td>Contact 10</td><td>contact10@example.org</td>
+  </tr>
+</tbody>
+```
+
+Scrolling that row into view issues `GET /_components/contact_rows?page=2`, whose response is the next `<tbody>` — appended after the first, ending in its own sentinel pointing at `page=3`. The last batch (`GET /_components/contact_rows?page=5`) contains only plain rows:
+
+```html
+<tbody id="contact-rows-5">
+  <tr><td>Contact 41</td><td>contact41@example.org</td></tr>
+  <tr><td>Contact 42</td><td>contact42@example.org</td></tr>
+</tbody>
+```
+
+## Related
+
+- [Click to Load](click-to-load.md) — the same batch-by-batch growth, but on the reader's explicit request.
+- [Lazy Loading](lazy-loading.md) — the `:visible` trigger deferring a single section instead of paginating many.
+- The [shorthands table](../dsl.md#shorthands) and [targets](../dsl.md#targets) in the DSL reference.

data/docs/examples/inline-expansion.md

@@ -0,0 +1,98 @@
+# Inline Expansion
+
+A compact row with a disclosure control. Clicking it fetches the row's detail from the server and inserts it directly beneath — the list stays a list, and depth appears exactly where the reader asked for it.
+
+There's no counterpart for this in the htmx examples catalog; `inline_expand:` is Weft-native sugar over the same [`loads:`](../dsl.md#loads) machinery as the other shorthands. It's the pattern for master-detail tables where the detail is cheap to want and expensive to preload for every row.
+
+## The components
+
+```ruby
+ORDERS = {
+  "1001" => { customer: "Ada Lovelace",       total: "$120.00", items: ["Brass gears (x12)", "Punch cards (x100)"] },
+  "1002" => { customer: "Grace Hopper",       total: "$45.50",  items: ["Nanosecond wire (x3)"] },
+  "1003" => { customer: "Katherine Johnson",  total: "$310.25", items: ["Slide rule", "Graph paper (x20)"] }
+}.freeze
+
+class OrderItemsRow < Weft::Component
+  builder_method :order_items_row
+
+  attribute :order_id
+
+  def tag_name
+    "tr"
+  end
+
+  def build(attributes = {})
+    super
+    order = ORDERS.fetch(attrs.order_id)
+    td colspan: 4 do
+      strong "Items: "
+      text_node order[:items].join(", ")
+    end
+  end
+end
+
+class OrdersTable < Weft::Component
+  builder_method :orders_table
+
+  def build(attributes = {})
+    super
+    table do
+      thead { tr { th ""; th "Order"; th "Customer"; th "Total" } }
+      tbody do
+        ORDERS.each do |id, order|
+          tr do
+            td do
+              button "▸", inline_expand: OrderItemsRow, with: { order_id: id },
+                          target: "closest tr", trigger: "click once"
+            end
+            td id
+            td order[:customer]
+            td order[:total]
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+(The `ORDERS` hash stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
+
+## How it works
+
+**The detail arrives *after* the trigger's row.** [`inline_expand:`](../dsl.md#shorthands) presets trigger `:click` and swap `:after` (htmx's `afterend`); the call site supplies the target. `target: "closest tr"` walks up from the button to its row, so the fetched component is inserted as the next sibling row — which is why `OrderItemsRow` overrides `tag_name` to render as a `<tr>`. A `colspan` spanning the table's columns lets the detail breathe across the full width.
+
+**`trigger: "click once"` guards against double insertion.** The preset's `:click` fires on *every* click — left alone, a second click would insert a second copy of the detail row. The `trigger:` kwarg overrides the preset with htmx's raw trigger grammar, and `once` caps the interaction at a single firing. (There's currently no semantic symbol for "click once" the way `:hover` bakes in `mouseenter once`, so the raw string is the honest spelling.)
+
+**Expansion, not a toggle.** Once expanded, the row stays expanded — this preset opens, it doesn't close. When you need collapse, give the detail component the behavior: a [`dismisses`](../dsl.md#dismisses--remove-from-the-dom) verb and a "Hide" button inside `OrderItemsRow` remove it from the DOM server-consistently. (The one-shot button does remain spent after that; a fully re-armable open/close control is a two-state component pair, as in [Click to Edit](click-to-edit.md).)
+
+## On the wire
+
+The initial render — each order row carries its wired disclosure button:
+
+```html
+<tr>
+  <td>
+    <button hx-get="/_components/order_items_row?order_id=1001" hx-swap="afterend"
+            hx-target="closest tr" hx-trigger="click once">▸</button>
+  </td>
+  <td>1001</td>
+  <td>Ada Lovelace</td>
+  <td>$120.00</td>
+</tr>
+```
+
+Clicking issues `GET /_components/order_items_row?order_id=1001`, and the response slots in beneath the row:
+
+```html
+<tr id="order-items-row-1001">
+  <td colspan="4"><strong>Items: </strong>Brass gears (x12), Punch cards (x100)</td>
+</tr>
+```
+
+## Related
+
+- [Tooltip](tooltip.md) — the other Weft-native shorthand: hover-driven detail loaded into a bubble instead of a row.
+- [Click to Edit](click-to-edit.md) — two-state rows that swap in place rather than expanding.
+- The [shorthands table](../dsl.md#shorthands) and [trigger values](../dsl.md#trigger-values) in the DSL reference.

data/docs/examples/inline-validation.md

@@ -0,0 +1,101 @@
+# Inline Validation
+
+A signup form's email field that checks itself: leave the field, and a moment later there's either a green all-clear or a specific complaint — straight from the server, before the user gets anywhere near the submit button.
+
+This is Weft's take on [htmx's inline-validation example](https://htmx.org/examples/inline-validation/), and the shape is the same: the field posts its value when it changes, the server decides, and the field's corner of the page re-renders with the verdict. In Weft the field is a small component that owns its whole validation story — the check, the error state, and the success state live next to the markup they decorate.
+
+## The components
+
+```ruby
+TAKEN_EMAILS = ["taken@example.com"].freeze
+
+class SignupEmailField < Weft::Component
+  builder_method :signup_email_field
+
+  attribute :email
+  attribute :error_message
+
+  performs :validate, target: "#signup-email-field" do |attrs|
+    email = attrs.email.to_s.strip
+    unless email.match?(URI::MailTo::EMAIL_REGEXP)
+      raise Weft::Unprocessable, "That doesn't look like an email address."
+    end
+    raise Weft::Unprocessable, "#{email} is already registered." if TAKEN_EMAILS.include?(email)
+
+    nil
+  end
+
+  recovers from: Weft::Unprocessable do |_attrs, error|
+    { error_message: error.message }
+  end
+
+  def build(attributes = {})
+    super
+    set_attribute :id, "signup-email-field"
+    form(action: :validate, trigger: "change") do
+      label "Email Address ", for: "email"
+      input type: "email", name: "email", id: "email", value: attrs.email
+    end
+    if attrs.error_message
+      para attrs.error_message, style: "color:#b91c1c"
+    elsif attrs.email
+      para "#{attrs.email} looks good.", style: "color:#15803d"
+    end
+  end
+end
+```
+
+(The `TAKEN_EMAILS` list stands in for the uniqueness check your real data layer would run.)
+
+## How it works
+
+**The field is a component, and the form belongs to the field.** `form(action: :validate, trigger: "change")` wires the POST like any action form, but `trigger:` swaps the form's natural submit trigger for `change` events — which bubble up from the input, so the request fires the moment the user leaves the field. A form's fields are its payload: the typed email reaches the callable as `attrs.email`, exactly as it would on a full submit.
+
+**Put the action on the form, not the input.** It's tempting to skip the form and hang `action: :validate, trigger: "change"` on the input itself. Don't: on a non-form element, `action:` carries the component's declared attributes along as `hx-vals`, and htmx gives those precedence over the triggering element's own value — so the request goes out with the *component's* stale idea of the email, never the fresh keystrokes. A one-field form is the honest wiring: what's in the field is what gets sent.
+
+**Validation failures are still renders.** Bad input raises `Weft::Unprocessable`; the `recovers from:` block catches it and returns `{ error_message: error.message }`, which merges into the attrs for the re-render. The response goes out as a semantic `422 Unprocessable Content` whose body is this same component wearing its error paragraph. Valid input sails through to the `nil` return and renders the success line at a plain `200`. (The machinery is [the `recovers` chain](../error-handling.md#the-recovers-chain); the merge is [the callable contract](../dsl.md#the-callable-contract).)
+
+**A value that changes can't anchor the DOM id.** Weft derives a component's DOM id from its first declared attribute — here that's the email itself, which would give the wrapper a different id on every render. So the component pins its own slot: `set_attribute :id, "signup-email-field"` fixes the wrapper's id, and `performs :validate, target: "#signup-email-field"` points the swap at that same anchor. (The same stable-slot idiom as [Bulk Update](bulk-update.md), for the same reason.)
+
+**The field echoes what the user typed.** The swap replaces the whole component, input included, so `value: attrs.email` writes the submitted text back into the fresh input — without it, every complaint would also blank the field.
+
+## On the wire
+
+The initial render (or `GET /_components/signup_email_field`) — one field, its form listening for `change`:
+
+```html
+<div id="signup-email-field">
+  <form hx-post="/_components/signup_email_field/validate" hx-target="#signup-email-field"
+        hx-swap="outerHTML" action="/_components/signup_email_field/validate" method="post"
+        hx-trigger="change">
+    <label for="email">Email Address </label>
+    <input type="email" name="email" id="email"/>
+  </form>
+</div>
+```
+
+Typing `not-an-email` and tabbing away posts `email=not-an-email`, and the answer is `422 Unprocessable Content` — the component re-rendered mid-complaint, the typed text still in the field:
+
+```html
+<div id="signup-email-field">
+  <form ...>
+    <label for="email">Email Address </label>
+    <input type="email" name="email" id="email" value="not-an-email"/>
+  </form>
+  <p style="color:#b91c1c">That doesn&#39;t look like an email address.</p>
+</div>
+```
+
+`taken@example.com` earns the other complaint the same way (`422`, "taken@example.com is already registered."), and `maria@example.com` comes back `200 OK` wearing the success line:
+
+```html
+  <p style="color:#15803d">maria@example.com looks good.</p>
+```
+
+And the part that makes it *inline*: a browser's `change` event on the input bubbles to the form and posts exactly what was typed — the captured request body is `email=typed.by.browser%40example.com`, no submit button involved.
+
+## Related
+
+- [Bulk Update](bulk-update.md) — the stable-slot idiom this page borrows, and reporting back through the returned hash.
+- [Click to Edit](click-to-edit.md) — the basics of pairing form fields with declared attributes.
+- [`performs`](../dsl.md#performs--user-initiated-actions), [`recovers`](../dsl.md#recovers--declare-error-behavior), and [`trigger:`](../dsl.md#trigger) in the DSL reference; [Error handling](../error-handling.md#the-recovers-chain) for the full recovery story.

data/docs/examples/keyboard-shortcuts.md

@@ -0,0 +1,71 @@
+# Keyboard Shortcuts
+
+A component action fired by a keystroke from anywhere on the page — the same request a click would make, bound to a key combination instead. No new machinery: a keyboard shortcut is just another trigger.
+
+This is Weft's take on [htmx's keyboard shortcuts example](https://htmx.org/examples/keyboard-shortcuts/), and the shape carries over directly: htmx's `hx-trigger` grammar already knows about key events, filters, and listening beyond the element itself, and Weft's [`trigger:`](../dsl.md#trigger) kwarg accepts that grammar in full.
+
+## The components
+
+```ruby
+INBOX_NOTE = { archived: false }
+
+class InboxNote < Weft::Component
+  builder_method :inbox_note
+
+  performs :archive do
+    INBOX_NOTE[:archived] = true
+    nil
+  end
+
+  def build(attributes = {})
+    super
+    if INBOX_NOTE[:archived]
+      para "Archived. Nothing left to do here."
+    else
+      para %("Lunch on Thursday?" — from Sam)
+      button "Archive (Alt+Shift+A)", action: :archive,
+             trigger: "click, keyup[altKey&&shiftKey&&key=='A'] from:body"
+    end
+  end
+end
+```
+
+(The `INBOX_NOTE` hash stands in for your data layer.)
+
+## How it works
+
+**`trigger:` accepts the full htmx grammar.** The semantic symbols in the [trigger table](../dsl.md#trigger-values) cover the common cases, but any string passes through to `hx-trigger` untouched — and that string can use everything [htmx's trigger syntax](https://htmx.org/attributes/hx-trigger/) offers. This one uses three pieces at once: *comma-separated triggers* (either one fires the request), an *event filter* in brackets (a JavaScript expression tested against the event), and a *`from:` modifier* (listen on `body`, not just the element).
+
+**Two triggers, one action.** [`action:`](../dsl.md#action) supplies what the request *is* — the POST to `:archive`, the target, the swap. `trigger:` only changes *when* it fires, replacing the button's default click-only trigger with click-or-keystroke. The button stays a button; the shortcut is an alternative route to the identical request.
+
+**`from:body` is what makes it a shortcut.** Without it, the keyup would only fire while the button itself had focus — which is no shortcut at all. Listening on `body` catches the key anywhere on the page. The filter then decides *which* keys: requiring `altKey && shiftKey` keeps the action from firing while someone merely types the letter into a text field. Bare-key bindings — `keyup[key=='/'] from:body` to jump to a search box, say — use the same grammar; just remember that unmodified letters and typing collide.
+
+## On the wire
+
+The initial render — one button carrying both the action wiring and the composite trigger:
+
+```html
+<div id="inbox-note">
+  <p>&quot;Lunch on Thursday?&quot; — from Sam</p>
+  <button hx-post="/_components/inbox_note/archive" hx-target="#inbox-note"
+          hx-swap="outerHTML" hx-vals="{}"
+          hx-trigger="click, keyup[altKey&amp;&amp;shiftKey&amp;&amp;key==&#39;A&#39;] from:body">
+    Archive (Alt+Shift+A)</button>
+</div>
+```
+
+The `&amp;&amp;` and `&#39;` are ordinary HTML attribute escaping — the browser decodes them before htmx reads the attribute, so htmx sees exactly the string you wrote: `click, keyup[altKey&&shiftKey&&key=='A'] from:body`.
+
+Clicking the button — or pressing Alt+Shift+A anywhere on the page — issues `POST /_components/inbox_note/archive`, and the re-rendered component replaces the note:
+
+```html
+<div id="inbox-note">
+  <p>Archived. Nothing left to do here.</p>
+</div>
+```
+
+## Related
+
+- The [trigger values table](../dsl.md#trigger-values) — the semantic symbols this page's raw string bypasses.
+- [Active Search](active-search.md) — another interaction defined almost entirely by its trigger.
+- [Modal Dialog](modal-dialog.md) — where the same grammar could bind Escape to a dismissal.