@hypermedia-components/cli 0.1.0

package/recipes/datagrid-pager/recipe.html

@@ -0,0 +1,30 @@
+<!-- datagrid-pager — server pagination for hc-datagrid (short form).
+     htmx swaps the rows INTO the <tbody> (innerHTML), so the <tbody> stays
+     put and installDatagrid's MutationObserver re-runs (roles, sticky
+     offsets, resized widths). The pager updates out-of-band. -->
+<div class="hc-datagrid">
+  <div class="hc-datagrid__scroll">
+    <table class="hc-datagrid__table">
+      <thead class="hc-datagrid__head">
+        <tr>
+          <th class="hc-datagrid__headcell" data-frozen data-frozen-edge scope="col">ID</th>
+          <th class="hc-datagrid__headcell" scope="col">Name</th>
+          <th class="hc-datagrid__headcell" scope="col">Price</th>
+        </tr>
+      </thead>
+      <!-- The swap target: rows replace #rows' children. -->
+      <tbody class="hc-datagrid__body" id="rows"
+             data-hx-get="/products?page=1" data-hx-trigger="load"
+             data-hx-target="#rows" data-hx-swap="innerHTML"></tbody>
+    </table>
+  </div>
+
+  <nav class="hc-pagination" id="pager" aria-label="Pagination">
+    <a class="hc-pagination__item" data-hx-get="/products?page=1"
+       data-hx-target="#rows" data-hx-swap="innerHTML" aria-current="page" href="?page=1">1</a>
+    <a class="hc-pagination__item" data-hx-get="/products?page=2"
+       data-hx-target="#rows" data-hx-swap="innerHTML" href="?page=2">2</a>
+    <a class="hc-pagination__item" data-hx-get="/products?page=3"
+       data-hx-target="#rows" data-hx-swap="innerHTML" href="?page=3">3</a>
+  </nav>
+</div>

package/recipes/field-errors/contract.md

@@ -0,0 +1,98 @@
+# field-errors — server response contract
+
+Purpose: render server-side validation errors next to the form fields
+they belong to, with correct ARIA wiring and **zero custom JavaScript**
+on the consumer side. The fragment below is the canonical wire format —
+template engines and code generators can emit it verbatim.
+
+## Required client markup
+
+- A `<form>` whose controls have `name` attributes (an `hc-field`
+  wrapper per control is recommended but not required).
+- An error container the response is swapped into — inside the form
+  (`<div id="form-errors"></div>` + `data-hx-target="#form-errors"`),
+  or anywhere else if the fragment points back at the form (see
+  `data-hc-field-errors` below).
+- `installFieldErrors()` (included in the auto-init
+  `@hypermedia-components/core/behaviors` bundle).
+
+## Server response (validation failure)
+
+Status: `422 Unprocessable Entity` (any status works — htmx ≥ 2 does
+not swap non-2xx responses by default; see “htmx wiring” below).
+
+```html
+<div class="hc-alert" data-variant="error" role="alert" data-hc-field-errors>
+  <p class="hc-alert__title">Unprocessable Entity</p>
+  <ul class="hc-alert__errors">
+    <li class="hc-alert__error" data-field="email" data-code="duplicate"
+        data-message-key="members.email.duplicate">email: duplicate</li>
+  </ul>
+  <p class="hc-alert__body">optional hint line</p>
+</div>
+```
+
+| Part | Required | Meaning |
+| --- | --- | --- |
+| `.hc-alert[data-variant="error"]` | yes | The summary container (the existing alert component). `role="alert"` makes screen readers announce the swap. |
+| `data-hc-field-errors` | yes | Behavior opt-in. Empty value: distribute into `closest('form')`. Non-empty value: a CSS selector for the form (use for out-of-band swaps or an alert rendered outside the form). |
+| `.hc-alert__title` | no | Summary line. |
+| `.hc-alert__errors` > `.hc-alert__error` | yes (≥ 0 items) | One `<li>` per field error. Repeating a `data-field` is allowed (messages render one per line). |
+| `data-field` | yes (per item) | The control's `name`. Radio/checkbox groups resolve via `form.elements` (the group's shared field receives the error). Items naming no known control stay visible in the summary. |
+| `data-code` | no | Machine-readable error code; passed to the message resolver as `{code}` and left on the element. |
+| `data-message-key` | no | A lookup key for client-side localization. Resolved through the i18n catalog (`setMessages()`); when the catalog has no such key, the `<li>` text renders instead. Servers that localize themselves just emit final text and omit this attribute. |
+| `data-message-params` | no | A JSON object of interpolation values for the catalog lookup (e.g. `data-message-params='{"stock": 5}'` for a translation using `{stock}`). Merged over the implicit `{field}`/`{code}` params (item values win). Malformed or non-object JSON is ignored — the fallback chain is unchanged. |
+| `data-summary="auto"` | no | Hide the whole alert once every item was distributed (for responses that carry only field errors). |
+| `data-focus="none"` | no | Don't focus the first invalid control. |
+| any other `data-*` (e.g. `data-error-code`) | no | Passed through untouched — consumer-specific metadata is fine. |
+
+## Client behavior
+
+On `htmx:afterSwap` / `htmx:oobAfterSwap` (plus a `MutationObserver`
+fallback and an install-time scan for full-page renders),
+`installFieldErrors()`:
+
+1. Clears all previous server errors in the target form.
+2. For each `.hc-alert__error[data-field]` whose `data-field` matches a
+   control: resolves the message (`data-message-key` via the i18n
+   catalog — interpolating `{field}`, `{code}` and any
+   `data-message-params` — → `<li>` text → `fieldErrors.unknown`),
+   writes it into the
+   field's `.hc-field__error` (created after a bare control when there
+   is no `.hc-field`), sets `aria-invalid="true"` +
+   `aria-describedby` on the control and `data-invalid="true"` on the
+   field, and marks the `<li>` `data-distributed="true"` (hidden in
+   the summary by CSS).
+3. Stamps the alert `data-distributed="all" | "partial" | "none"` and
+   focuses the first invalid control.
+
+A field's server error is cleared as soon as the user edits that field
+(`input`/`change`), when the form is submitted again or reset, and
+before a newly swapped-in fragment is distributed. Native constraint
+validation (`installValidation()`) outranks a server error on the same
+control — the native message reflects the current value.
+
+## htmx wiring
+
+htmx does not swap non-2xx responses by default. Allow the 422 swap
+once, globally:
+
+```js
+document.body.addEventListener('htmx:beforeSwap', (event) => {
+  if (event.detail.xhr.status === 422) {
+    event.detail.shouldSwap = true;
+    event.detail.isError = false;
+  }
+});
+```
+
+Alternatively respond `200` with the fragment, or send
+`HX-Retarget: #form-errors` + `HX-Reswap: innerHTML` headers to
+redirect an arbitrary response into the error container.
+
+## Progressive enhancement
+
+Without JavaScript (full-page re-render of the form + fragment), the
+summary alert renders all errors as a plain list — nothing is lost;
+distribution is an enhancement. Without htmx, the install-time scan
+distributes errors present in the initial HTML.

package/recipes/field-errors/expanded.html

@@ -0,0 +1,44 @@
+<!-- Fully expanded HTML. -->
+
+<!-- The form. The error container is the htmx target for non-2xx
+     responses (wire htmx:beforeSwap to allow 422 swaps — see contract). -->
+<form data-hx-post="/members"
+      data-hx-target="#form-errors"
+      data-hx-swap="innerHTML"
+      data-hx-disabled-elt="find button[type=submit]">
+  <div id="form-errors"></div>
+
+  <div class="hc-field">
+    <label class="hc-field__label" for="email">Email</label>
+    <input class="hc-input" id="email" name="email" type="email" required
+           aria-describedby="email-help">
+    <p class="hc-field__message" id="email-help">We never share it.</p>
+    <!-- installFieldErrors() / installValidation() fill this slot; it is
+         created automatically when absent. -->
+    <p class="hc-field__error" aria-live="polite"></p>
+  </div>
+
+  <button type="submit" class="hc-button" data-variant="primary">Save</button>
+</form>
+
+<!-- Server fragment, swapped into #form-errors on a 422. -->
+<div class="hc-alert" data-variant="error" role="alert"
+     data-hc-field-errors
+     data-error-code="APP-FIELD-4220">
+  <p class="hc-alert__title">Unprocessable Entity</p>
+  <ul class="hc-alert__errors">
+    <li class="hc-alert__error"
+        data-field="email"
+        data-code="duplicate"
+        data-message-key="members.email.duplicate">email: duplicate</li>
+  </ul>
+  <p class="hc-alert__body">Optional hint line (e.g. an optimistic-locking conflict).</p>
+</div>
+
+<!-- After distribution the behavior has:
+     - written the message into the field's .hc-field__error,
+     - set aria-invalid + aria-describedby on the input and
+       data-invalid on the field,
+     - marked the <li> data-distributed="true" (hidden in the summary),
+     - stamped the alert data-distributed="all|partial|none",
+     - focused the first invalid control (opt out: data-focus="none"). -->

package/recipes/field-errors/recipe.html

@@ -0,0 +1,21 @@
+<!-- Short recommended usage. -->
+<form data-hx-post="/members" data-hx-target="#form-errors" data-hx-swap="innerHTML">
+  <div id="form-errors"></div>
+
+  <div class="hc-field">
+    <label class="hc-field__label" for="email">Email</label>
+    <input class="hc-input" id="email" name="email" type="email" required>
+  </div>
+
+  <button type="submit" class="hc-button" data-variant="primary">Save</button>
+</form>
+
+<!-- Server response on validation failure (422). installFieldErrors()
+     distributes each item to the field named by data-field. -->
+<div class="hc-alert" data-variant="error" role="alert" data-hc-field-errors>
+  <p class="hc-alert__title">Please fix the errors below.</p>
+  <ul class="hc-alert__errors">
+    <li class="hc-alert__error" data-field="email" data-code="duplicate"
+        data-message-key="members.email.duplicate">email: duplicate</li>
+  </ul>
+</div>

package/recipes/filter-popover/contract.md

@@ -0,0 +1,18 @@
+# filter-popover — server response contract
+
+Purpose: a popover that holds a filter form. Submitting the form sends an htmx request and closes the popover.
+
+## Required client markup
+
+- A trigger `<button popovertarget="...">`.
+- A `<div class="hc-popover" popover>` with a form inside.
+- The form has `data-hx-get` (or `post`), `data-hx-target`, and `data-hc-close-popover-on-success`.
+
+## Server response
+
+- Return HTML for the `data-hx-target` element.
+- Status `2xx` triggers `hc.behaviors.js` to call `hidePopover()` on the closest `[popover]`.
+
+## Accessibility
+
+The popover is not implicitly a menu. If you need menu keyboard behavior, build it explicitly with roles and handlers — do not assume the popover provides it.

package/recipes/filter-popover/expanded.html

@@ -0,0 +1,25 @@
+<!-- Fully expanded HTML. -->
+<button
+  class="hc-button"
+  type="button"
+  popovertarget="filter-popover"
+  aria-expanded="false">
+  Filter
+</button>
+
+<div id="filter-popover" class="hc-popover" popover>
+  <form
+    class="hc-form"
+    data-hx-get="/items"
+    data-hx-target="#results"
+    data-hx-swap="innerHTML"
+    data-hc-close-popover-on-success>
+    <!-- filter fields here -->
+    <footer class="hc-popover__footer">
+      <button class="hc-button" type="reset">Reset</button>
+      <button class="hc-button" type="submit" data-variant="primary">Apply</button>
+    </footer>
+  </form>
+</div>
+
+<div id="results"></div>

package/recipes/filter-popover/recipe.html

@@ -0,0 +1,17 @@
+<!-- Short recommended usage. -->
+<button class="hc-button" type="button" popovertarget="filter-popover">
+  Filter
+</button>
+
+<div id="filter-popover" class="hc-popover" popover>
+  <form
+    class="hc-form"
+    data-hx-get="/items"
+    data-hx-target="#results"
+    data-hc-close-popover-on-success>
+    <!-- filter fields here -->
+    <button class="hc-button" type="submit" data-variant="primary">Apply</button>
+  </form>
+</div>
+
+<div id="results"></div>

package/recipes/inline-edit/contract.md

@@ -0,0 +1,58 @@
+# inline-edit — server response contract
+
+Purpose: toggle a cell between a display rendering and an editable
+form, swapping the same DOM node each way. No client behavior beyond
+htmx — the recipe is purely a server-side state machine.
+
+## Endpoints
+
+| Method | URL                    | Returns                                    |
+| ------ | ---------------------- | ------------------------------------------ |
+| GET    | `/items/:id/name`      | Display fragment (HTML)                    |
+| GET    | `/items/:id/name/edit` | Edit-form fragment (HTML)                  |
+| PUT    | `/items/:id/name`      | 200 + display fragment, **or** 422 + edit fragment |
+
+All three return HTML, never JSON. The Cancel button hits
+`GET /items/:id/name` to re-render the display state.
+
+## Required client markup
+
+- Display and edit fragments share the same `id` so the
+  `data-hx-swap="outerHTML"` swap replaces the entire node each way.
+- Display fragment: `data-hx-get="…/edit"`,
+  `data-hx-trigger="click"`, `data-hx-target="this"`.
+- Edit fragment: `<form data-hx-put="…">`,
+  `data-hx-target="this"`, `data-hx-swap="outerHTML"`.
+
+## Save flow
+
+1. User clicks the display node. htmx fetches `GET /items/42/name/edit`
+   and swaps the response in place.
+2. User types and submits the form.
+3. Server validates.
+   - **Success** — return the updated display fragment with 200.
+     `outerHTML` swap replaces the `<form>` with the new `<span>`;
+     htmx re-processes the new attributes.
+   - **Failure** — return the edit fragment with 422 (or 200 +
+     `HX-Reswap: outerHTML`). Include `aria-invalid="true"` and an
+     `aria-describedby` message inside an `.hc-field[data-invalid]`
+     wrapper.
+
+## htmx settings
+
+For 4xx responses to be swapped (so validation errors appear in the
+page), one of:
+
+- Set the global `htmx.config.responseHandling` to treat 422 as
+  swap-eligible; or
+- Add `HX-Reswap: outerHTML` and `HX-Retarget: this` headers; or
+- Use `data-hx-target-422="this"` on the form to opt the specific
+  status code in.
+
+## Optimistic interactions
+
+If you want save-on-blur instead of an explicit Save button, add
+`data-hx-trigger="blur"` on the input and skip the buttons. Keep the
+form wrapper for `name`-based field submission. The Cancel path is
+then `Escape` plus a small inline behavior that calls
+`GET /items/:id/name`.

package/recipes/inline-edit/expanded.html

@@ -0,0 +1,70 @@
+<!-- Fully expanded HTML.
+
+  Three server-rendered fragments at the same id share one DOM slot;
+  htmx swaps between them with `outerHTML`. No client behavior beyond
+  htmx itself. -->
+
+<!-- 1. Display state (initial render and after successful save).
+     URL: GET /items/42/name -->
+<span
+  id="item-42-name"
+  data-hx-get="/items/42/name/edit"
+  data-hx-trigger="click"
+  data-hx-target="this"
+  data-hx-swap="outerHTML"
+  style="cursor: pointer;">
+  Acme widgets
+</span>
+
+<!-- 2. Edit state (returned by GET /items/42/name/edit). -->
+<form
+  id="item-42-name"
+  data-hx-put="/items/42/name"
+  data-hx-target="this"
+  data-hx-swap="outerHTML"
+  style="display: inline-flex; gap: .25rem;">
+  <input
+    name="name"
+    class="hc-input"
+    data-size="sm"
+    value="Acme widgets"
+    autofocus>
+  <button class="hc-button" data-size="sm" data-variant="primary" type="submit">
+    Save
+  </button>
+  <button class="hc-button" data-size="sm" type="button"
+    data-hx-get="/items/42/name"
+    data-hx-target="this"
+    data-hx-swap="outerHTML">
+    Cancel
+  </button>
+</form>
+
+<!-- 3. Edit state with a validation error (PUT returned 422 with
+        HX-Reswap: outerHTML or `data-hx-swap-oob`). Same id so the
+        outerHTML swap targets the same node. -->
+<form
+  id="item-42-name"
+  data-hx-put="/items/42/name"
+  data-hx-target="this"
+  data-hx-swap="outerHTML">
+  <div class="hc-field" data-invalid="true">
+    <input
+      class="hc-input"
+      data-size="sm"
+      name="name"
+      value=""
+      aria-invalid="true"
+      aria-describedby="item-42-name-error">
+    <p id="item-42-name-error" class="hc-field__message">Name is required.</p>
+  </div>
+  <button class="hc-button" data-size="sm" data-variant="primary" type="submit">
+    Save
+  </button>
+  <button class="hc-button" data-size="sm" type="button"
+    data-hx-get="/items/42/name"
+    data-hx-target="this"
+    data-hx-swap="outerHTML">
+    Cancel
+  </button>
+</form>

package/recipes/inline-edit/recipe.html

@@ -0,0 +1,12 @@
+<!-- Short recommended usage.
+
+  The display state of an editable cell. Clicking swaps it with the
+  edit-form fragment returned by /items/42/name/edit. -->
+<span
+  id="item-42-name"
+  data-hx-get="/items/42/name/edit"
+  data-hx-trigger="click"
+  data-hx-target="this"
+  style="cursor: pointer;">
+  Acme widgets
+</span>

package/recipes/lazy-panel/contract.md

@@ -0,0 +1,67 @@
+# lazy-panel — server response contract
+
+Purpose: defer a region's content fetch until the user actually
+encounters it — scroll, accordion open, or tab activation. The
+recipe is purely htmx attributes; no behavior helper is needed.
+
+## Required client markup
+
+One of three trigger forms, all `once` so the fetch never repeats:
+
+| Trigger                                  | Activated by                           |
+| ---------------------------------------- | -------------------------------------- |
+| `intersect once`                         | The panel scrolls into the viewport.   |
+| `toggle from:closest details once`       | An ancestor `<details>` opens.         |
+| `reveal once`                            | The panel's `hidden` attribute is removed (tab activation). |
+
+Required attributes on the panel:
+
+- `data-hx-get="…"` — the URL that returns the panel content.
+- `data-hx-trigger="…"` — one of the forms above.
+- `data-hx-swap="innerHTML"` — replace the placeholder, keep the
+  wrapper.
+
+Optional:
+
+- `data-hx-indicator="this"` to fade in a spinner / skeleton while
+  the request is in flight (style via `.htmx-indicator`).
+
+## Server response
+
+Return the panel body HTML. No special headers required. If the
+panel needs cache headers (typical for dashboards), set them as
+usual:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/html; charset=utf-8
+Cache-Control: private, max-age=60
+
+<div class="hc-card">
+  ...
+</div>
+```
+
+## Failure handling
+
+A 4xx/5xx leaves the placeholder in place by default. To show an
+error message in the same slot, return the error body with
+`HX-Reswap: innerHTML`:
+
+```http
+HTTP/1.1 503 Service Unavailable
+HX-Reswap: innerHTML
+
+<p class="hc-alert" data-variant="error" role="alert">
+  Reports are temporarily unavailable. Refresh in a minute.
+</p>
+```
+
+## Combined with toast
+
+Server can also signal a toast in the same response by adding
+`HX-Trigger` — useful for non-fatal warnings ("data is stale").
+
+```http
+HX-Trigger: {"hc:toast":{"message":"Data may be up to 5 minutes old","variant":"warning"}}
+```

package/recipes/lazy-panel/expanded.html

@@ -0,0 +1,68 @@
+<!-- Fully expanded HTML.
+
+  Three trigger variants for the same "load on first reveal" pattern.
+  Pick the one that matches how the panel becomes relevant. -->
+
+<!-- Variant 1 — on intersection (panel scrolls into view).
+     `intersect once threshold:0.25` waits until 25% is visible. -->
+<section
+  data-hx-get="/dashboards/usage"
+  data-hx-trigger="intersect once"
+  data-hx-swap="innerHTML"
+  data-hx-indicator="this">
+  <p class="hc-field__message">Loading when visible…</p>
+</section>
+
+<!-- Variant 2 — on <details> open (accordion).
+     `from:closest details` listens for the toggle on the ancestor.
+     `once` makes sure the fetch never repeats. -->
+<details>
+  <summary>Advanced settings</summary>
+  <div
+    data-hx-get="/settings/advanced"
+    data-hx-trigger="toggle from:closest details once"
+    data-hx-swap="innerHTML"
+    data-hx-indicator="this">
+    <p class="hc-field__message">Loading…</p>
+  </div>
+</details>
+
+<!-- Variant 3 — on tab activation.
+     The tablist owns the aria-selected / hidden flipping (any tab
+     library will do). The inactive tab panel uses `reveal once`,
+     which fires when its `hidden` attribute is removed. -->
+<div role="tablist" aria-label="Reports">
+  <button
+    role="tab"
+    aria-controls="panel-overview"
+    aria-selected="true"
+    data-tab-target="panel-overview">
+    Overview
+  </button>
+  <button
+    role="tab"
+    aria-controls="panel-revenue"
+    aria-selected="false"
+    data-tab-target="panel-revenue">
+    Revenue
+  </button>
+</div>
+
+<section
+  id="panel-overview"
+  role="tabpanel"
+  data-hx-get="/reports/overview"
+  data-hx-trigger="load"
+  data-hx-swap="innerHTML"
+  data-hx-indicator="this">
+</section>
+
+<section
+  id="panel-revenue"
+  role="tabpanel"
+  hidden
+  data-hx-get="/reports/revenue"
+  data-hx-trigger="reveal once"
+  data-hx-swap="innerHTML"
+  data-hx-indicator="this">
+</section>

package/recipes/lazy-panel/recipe.html

@@ -0,0 +1,11 @@
+<!-- Short recommended usage.
+
+  A region whose content is fetched on first reveal. `intersect once`
+  uses IntersectionObserver and only fires the first time the panel
+  enters the viewport. -->
+<section
+  data-hx-get="/dashboards/usage"
+  data-hx-trigger="intersect once"
+  data-hx-indicator="this">
+  <p class="hc-field__message">Loading when visible…</p>
+</section>

package/recipes/live-search/contract.md

@@ -0,0 +1,21 @@
+# live-search — server response contract
+
+Purpose: send a search request as the user types and swap the results.
+
+## Required client markup
+
+- `<form role="search">` with a `GET` action so it works without JavaScript.
+- `data-hx-get` on the input — same URL as the form action.
+- `data-hx-trigger="input changed delay:300ms, search"` — debounce typing, also respond to the `search` event.
+- `data-hx-target="#results"` and `data-hx-swap="innerHTML"`.
+- `data-hx-sync="closest form:replace"` — cancel in-flight requests when a newer one starts.
+
+## Server response
+
+- Return HTML for `#results`.
+- Include empty-state markup when there are no results.
+- Keep the normal form `GET` working without JavaScript.
+
+Status: `200 OK` with the fragment. htmx ≥ 2 does not swap non-2xx
+responses by default, so on a server error the previous results stay in
+place — return `2xx` only when the fragment should replace them.

package/recipes/live-search/expanded.html

@@ -0,0 +1,17 @@
+<!-- Fully expanded HTML. -->
+<form class="hc-search" action="/items" method="get" role="search">
+  <input
+    class="hc-input"
+    type="search"
+    name="q"
+    placeholder="Search"
+    data-hx-get="/items"
+    data-hx-trigger="input changed delay:300ms, search"
+    data-hx-target="#results"
+    data-hx-swap="innerHTML"
+    data-hx-sync="closest form:replace">
+
+  <button class="hc-button" type="submit">Search</button>
+</form>
+
+<div id="results"></div>

package/recipes/live-search/recipe.html

@@ -0,0 +1,15 @@
+<!-- Short recommended usage. -->
+<form class="hc-search" action="/items" method="get" role="search">
+  <input
+    class="hc-input"
+    type="search"
+    name="q"
+    placeholder="Search"
+    data-hx-get="/items"
+    data-hx-trigger="input changed delay:300ms, search"
+    data-hx-target="#results"
+    data-hx-swap="innerHTML">
+  <button class="hc-button" type="submit">Search</button>
+</form>
+
+<div id="results"></div>

package/recipes/remote-dialog/contract.md

@@ -0,0 +1,20 @@
+# remote-dialog — server response contract
+
+Purpose: open a dialog whose contents are fetched from the server.
+
+## Required client markup
+
+- Trigger element with `data-hx-get`, `data-hx-target="#dialog-root"`, `data-hx-swap="innerHTML"`.
+- Mount point `<div id="dialog-root" data-hc-remote-dialog-root></div>` somewhere on the page.
+
+## Server response
+
+Return a complete `<dialog class="hc-dialog">` element with the dialog content (title, body, footer, form). The dialog should not already be `open`.
+
+Status: `200 OK` with the fragment. A non-2xx response is not swapped
+(htmx ≥ 2 default), so no dialog opens — surface the failure via an
+`HX-Trigger` toast (see the toast recipe) if the user needs feedback.
+
+## Client behavior
+
+After the swap into `#dialog-root`, `hc.behaviors.js` finds the first `<dialog>` and calls `showModal()`. Forms inside the dialog can use `data-hc-close-dialog-on-success` to close after a successful submission.

package/recipes/remote-dialog/expanded.html

@@ -0,0 +1,18 @@
+<!-- Fully expanded HTML — what the server returns inside #dialog-root. -->
+<dialog class="hc-dialog">
+  <header class="hc-dialog__header">
+    <h2 class="hc-dialog__title">Edit item</h2>
+  </header>
+
+  <form
+    class="hc-form"
+    data-hx-post="/items/123"
+    data-hx-target="closest dialog"
+    data-hx-swap="outerHTML">
+    <!-- form fields here -->
+    <footer class="hc-dialog__footer">
+      <button class="hc-button" type="button">Cancel</button>
+      <button class="hc-button" data-variant="primary" type="submit">Save</button>
+    </footer>
+  </form>
+</dialog>

package/recipes/remote-dialog/recipe.html

@@ -0,0 +1,10 @@
+<!-- Short recommended usage. -->
+<button
+  class="hc-button"
+  data-hx-get="/items/123/edit"
+  data-hx-target="#dialog-root"
+  data-hx-swap="innerHTML">
+  Edit
+</button>
+
+<div id="dialog-root" data-hc-remote-dialog-root></div>