@hypermedia-components/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ingcreators
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @hypermedia-components/cli
+
+Copy [Hypermedia Components](https://github.com/ingcreators/hypermedia-components)
+recipe scaffolds into your project. Recipes are **source files you own** —
+plain HTML plus a documented server contract — not a runtime dependency.
+
+```bash
+npx @hypermedia-components/cli list
+npx @hypermedia-components/cli add confirm-action
+npx @hypermedia-components/cli add live-search --dir src/recipes
+```
+
+`add <recipe>` copies three files into `<dir>/<recipe>/`:
+
+| File | What it is |
+| --- | --- |
+| `recipe.html` | The copyable starting point (semantic classes + `data-hx-*`). |
+| `expanded.html` | The same pattern with every shorthand expanded. |
+| `contract.md` | The server request/response contract the recipe expects. |
+
+Existing files are never overwritten unless you pass `--force`.
+
+The recipes ship inside this package, so the command works offline. Each
+recipe is documented with a live demo on the
+[docs site](https://hypermedia-components.ichimura-12c.workers.dev/hypermedia-components/recipes/).
+
+The styles and behaviors the recipes reference come from
+[`@hypermedia-components/core`](https://www.npmjs.com/package/@hypermedia-components/core).

package/bin/hc-cli.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// npx @hypermedia-components/cli add <recipe> [--dir <target>] [--force]
+// npx @hypermedia-components/cli list
+import { parseArgs } from 'node:util';
+import { listRecipes, copyRecipe, RECIPE_FILES } from '../lib/recipes.mjs';
+
+const USAGE = `Usage:
+  hypermedia-components add <recipe> [--dir <target>] [--force]
+  hypermedia-components list
+
+Commands:
+  add    Copy a recipe's source files (${RECIPE_FILES.join(' / ')})
+         into <target>/<recipe>/ (target defaults to the current directory).
+  list   Show the available recipes.
+
+Options:
+  -d, --dir <target>   Directory to copy into (default: ".")
+  -f, --force          Overwrite existing files
+  -h, --help           Show this help
+`;
+
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      dir: { type: 'string', short: 'd', default: '.' },
+      force: { type: 'boolean', short: 'f', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  const [command, name] = positionals;
+
+  if (values.help || !command || command === 'help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  if (command === 'list') {
+    for (const recipe of await listRecipes()) {
+      process.stdout.write(`${recipe.name.padEnd(18)} ${recipe.purpose}\n`);
+    }
+    return 0;
+  }
+
+  if (command === 'add') {
+    if (!name) {
+      process.stderr.write(`Missing recipe name.\n\n${USAGE}`);
+      return 1;
+    }
+    const written = await copyRecipe(name, values.dir, { force: values.force });
+    for (const file of written) process.stdout.write(`${file}\n`);
+    process.stdout.write(
+      `\nCopied ${written.length} files. recipe.html is the starting point; ` +
+        `contract.md documents the server responses it expects.\n`,
+    );
+    return 0;
+  }
+
+  process.stderr.write(`Unknown command ${JSON.stringify(command)}.\n\n${USAGE}`);
+  return 1;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(error.message.startsWith('Refusing to overwrite') ? 2 : 1);
+  },
+);

package/lib/recipes.mjs

@@ -0,0 +1,77 @@
+// Recipe resolution + copying. The published tarball bundles a synced
+// copy of the repo's recipes/ (created by scripts/sync-recipes.mjs at
+// prepack), so the CLI works offline; inside the workspace the repo's
+// recipes/ directory itself is used, so dev never needs a sync step.
+import { cp, mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The three files every recipe ships (the recipe DoD's source format). */
+export const RECIPE_FILES = ['recipe.html', 'expanded.html', 'contract.md'];
+
+/** Bundled copy first (published tarball), repo root second (workspace dev). */
+export function recipesRoot() {
+  for (const candidate of [join(PKG_ROOT, 'recipes'), resolve(PKG_ROOT, '..', '..', 'recipes')]) {
+    if (existsSync(join(candidate))) return candidate;
+  }
+  throw new Error('No recipes directory found (looked in the package and the workspace root).');
+}
+
+/** @returns {Promise<Array<{ name: string, purpose: string }>>} sorted by name */
+export async function listRecipes() {
+  const root = recipesRoot();
+  const entries = await readdir(root, { withFileTypes: true });
+  const recipes = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!existsSync(join(root, entry.name, 'recipe.html'))) continue;
+    const contract = await readFile(join(root, entry.name, 'contract.md'), 'utf8').catch(() => '');
+    const purpose = contract.match(/^Purpose:\s*(.+)$/m)?.[1]?.trim() ?? '';
+    recipes.push({ name: entry.name, purpose });
+  }
+  return recipes.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Copy a recipe's source files into `<targetDir>/<name>/`.
+ *
+ * @param {string} name
+ * @param {string} targetDir
+ * @param {{ force?: boolean }} [opts]
+ * @returns {Promise<string[]>} the written file paths
+ */
+export async function copyRecipe(name, targetDir, { force = false } = {}) {
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error(`Invalid recipe name: ${JSON.stringify(name)} (expected kebab-case).`);
+  }
+  const source = join(recipesRoot(), name);
+  const known = await listRecipes();
+  if (!known.some((r) => r.name === name)) {
+    throw new Error(
+      `Unknown recipe ${JSON.stringify(name)}. Available: ${known.map((r) => r.name).join(', ')}`,
+    );
+  }
+
+  const dest = join(resolve(targetDir), name);
+  if (!force) {
+    for (const file of RECIPE_FILES) {
+      const target = join(dest, file);
+      if (existsSync(target)) {
+        throw new Error(`Refusing to overwrite ${target} (pass --force to replace).`);
+      }
+    }
+  }
+
+  await mkdir(dest, { recursive: true });
+  const written = [];
+  for (const file of RECIPE_FILES) {
+    const from = join(source, file);
+    if (!(await stat(from).catch(() => null))) continue;
+    await cp(from, join(dest, file), { force: true });
+    written.push(join(dest, file));
+  }
+  return written;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hypermedia-components/cli",
+  "version": "0.1.0",
+  "description": "Copy Hypermedia Components recipe scaffolds (recipe.html / expanded.html / contract.md) into your project.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ingcreators/hypermedia-components.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "hypermedia-components": "bin/hc-cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "recipes/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/recipes/chart/contract.md

@@ -0,0 +1,136 @@
+# chart — server response contract
+
+Purpose: render a chart from a server-sent **semantic data table**. The
+table is the data source, the no-JavaScript fallback, and the
+screen-reader data. `installChart()` (from `@hypermedia-components/core`)
+reads it and draws an [Observable Plot](https://observablehq.com/plot/)
+SVG. Plot is an optional peer dependency — load it yourself (CDN UMD
+global or a bundled import); without it the table simply stays visible.
+
+This recipe **needs a behavior**: `installChart(document, { plot })`. It is
+**not** part of the auto-init `@hypermedia-components/core/behaviors`
+entry, because Plot is not bundled.
+
+## Required client markup
+
+- `<figure class="hc-chart" data-hc-chart="<type>">` wrapping a
+  `<table class="hc-table">`.
+- A `<thead>` whose first cell is the **x category** and whose remaining
+  cells name the **series**.
+- A `<tbody>` of rows: first cell = x value, the rest = series values.
+- Optional `<caption>` — used as the chart title.
+
+```html
+<figure class="hc-chart" data-hc-chart="line" data-y-label="Sales ($k)">
+  <table class="hc-table">
+    <caption>Monthly sales</caption>
+    <thead><tr><th>Month</th><th>Tokyo</th><th>Osaka</th></tr></thead>
+    <tbody>
+      <tr><td>Jan</td><td>120</td><td>80</td></tr>
+      <tr><td>Feb</td><td>200</td><td>140</td></tr>
+    </tbody>
+  </table>
+</figure>
+```
+
+## Chart types (`data-hc-chart`)
+
+| Value   | Renders                                                        |
+| ------- | ------------------------------------------------------------- |
+| `bar`   | Vertical bars. Multiple series **stack**.                     |
+| `line`  | Lines with node dots, one per series.                         |
+| `area`  | Filled areas with a line edge, one per series.                |
+| `combo` | Per-column marks — set each `<th data-mark="bar\|line\|area">`. |
+
+`data-hc-chart` is the **default mark** for any column without its own
+`data-mark`. For `combo` the default is `bar`. So `bar`/`line`/`area` are
+just the special case where every column shares one mark.
+
+## Per-column mark (combo)
+
+```html
+<thead>
+  <tr>
+    <th>Month</th>
+    <th data-mark="bar">Sales</th>
+    <th data-mark="line">Target</th>
+  </tr>
+</thead>
+```
+
+## Options (figure attributes)
+
+| Attribute              | Default      | Effect                                            |
+| ---------------------- | ------------ | ------------------------------------------------- |
+| `data-y-label`         | _(none)_     | y-axis label.                                     |
+| `data-title`           | `<caption>`  | Chart title (falls back to the table caption).    |
+| `data-x-type`          | `category`   | `category` \| `number` \| `date` — x value coercion. |
+| `data-width`           | container    | Plot width in px.                                 |
+| `data-height`          | `--hc-chart-height` (320px) | Plot height in px.                 |
+| `data-legend`          | auto         | `false` hides the colour legend.                  |
+
+Cell values are coerced to numbers; thousands separators, currency
+symbols, and `%` signs are stripped (`"1,200"` → `1200`). Bars expect a
+`category` x; `number` / `date` x suit `line` / `area`.
+
+## Server response
+
+Return the `<figure class="hc-chart">…</figure>` fragment (or just the
+inner table for an existing figure target). The **same** endpoint must
+return a usable table for a non-htmx request (full page load) so the
+no-JavaScript path works — detect htmx via the `HX-Request: true` header
+if you wrap fragments in a layout.
+
+```html
+<!-- GET /reports/sales -->
+<figure class="hc-chart" data-hc-chart="bar" data-y-label="Sales ($k)">
+  <table class="hc-table">
+    <caption>Monthly sales</caption>
+    <thead><tr><th>Month</th><th>Sales</th></tr></thead>
+    <tbody>
+      <tr><td>Jan</td><td>120</td></tr>
+      <tr><td>Feb</td><td>200</td></tr>
+    </tbody>
+  </table>
+</figure>
+```
+
+`installChart` listens for `htmx:load`, so a chart swapped into the page
+renders automatically — no per-swap JavaScript.
+
+Status: `200 OK` with the fragment for htmx requests *and* for the
+full-page (no-JavaScript) request. A non-2xx response is not swapped
+(htmx ≥ 2 default), so the previous chart stays.
+
+## Optional: embedded JSON source
+
+For many series or config-heavy charts you may prefer embedding the data
+as JSON instead of (or alongside) the table. This recipe's behavior reads
+the **table**; if you adopt a JSON source, **escape `<` as `<`** when
+serializing server-side to avoid breaking out of the `<script>` element
+(an XSS vector with user data). Keep a visually-hidden table for the
+no-JavaScript / screen-reader path.
+
+## Progressive enhancement
+
+- **No JavaScript** → the `<table class="hc-table">` renders as a normal,
+  readable data table.
+- **JavaScript, no Plot** → same: `installChart` is a no-op without Plot.
+- **JavaScript + Plot** → the table is moved into the accessibility tree
+  (`.hc-sr-only`) and the SVG chart is shown.
+
+## Accessibility
+
+- The source table is **kept** (hidden with `.hc-sr-only`, not removed),
+  so assistive tech reads the full tabular data.
+- The rendered `<svg>` is `aria-hidden="true"` — it is a decorative
+  duplicate of the table, so it is not announced twice.
+- Give the table a `<caption>` describing the chart.
+
+## Server-side rendering (alternative)
+
+Charts can also be rendered to SVG on the server with Plot under a DOM
+shim (linkedom) and returned inline, with **no client Plot**. Set
+explicit `marginLeft` / `marginBottom` then, since server DOM shims do not
+measure text for automatic axis margins. This recipe implements the
+client-side path; the SSR path is documented for completeness.

package/recipes/chart/expanded.html

@@ -0,0 +1,40 @@
+<!-- Fully expanded usage. -->
+
+<!-- 1. Load Observable Plot (an optional peer dependency — bring your own)
+     and install the behavior once per page. Here Plot is the UMD global
+     from a CDN; installChart picks it up via window.Plot automatically,
+     but passing it explicitly is clearer. -->
+<script src="https://cdn.jsdelivr.net/npm/@observablehq/plot@0.6/dist/plot.umd.min.js"></script>
+<script type="module">
+  import { installChart } from '@hypermedia-components/core';
+  installChart(document, { plot: window.Plot });
+</script>
+
+<!-- 2. A combo chart — a bar series and a line series, declared per column
+     with data-mark. data-hc-chart="combo" makes "bar" the default for any
+     column without an explicit data-mark. -->
+<figure class="hc-chart" data-hc-chart="combo" data-y-label="Sales ($k)">
+  <table class="hc-table">
+    <caption>Monthly sales vs target</caption>
+    <thead>
+      <tr>
+        <th>Month</th>
+        <th data-mark="bar">Sales</th>
+        <th data-mark="line">Target</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>Jan</td><td>120</td><td>150</td></tr>
+      <tr><td>Feb</td><td>200</td><td>160</td></tr>
+      <tr><td>Mar</td><td>150</td><td>170</td></tr>
+    </tbody>
+  </table>
+</figure>
+
+<!-- 3. htmx — a region that swaps in a server-rendered chart table.
+     installChart re-renders on htmx:load, so swapped-in charts draw
+     themselves with no extra wiring. -->
+<div data-hx-get="/reports/sales" data-hx-trigger="load" data-hx-swap="innerHTML">
+  <!-- The server returns the <figure class="hc-chart">…</figure> fragment.
+       Without JavaScript this GET still returns a readable table. -->
+</div>

package/recipes/chart/recipe.html

@@ -0,0 +1,16 @@
+<!-- Short recommended usage. The <table> is the data source AND the
+     no-JavaScript / no-Plot accessible fallback. installChart() reads it
+     and draws the chart. -->
+<figure class="hc-chart" data-hc-chart="bar" data-y-label="Sales ($k)">
+  <table class="hc-table">
+    <caption>Monthly sales</caption>
+    <thead>
+      <tr><th>Month</th><th>Sales</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Jan</td><td>120</td></tr>
+      <tr><td>Feb</td><td>200</td></tr>
+      <tr><td>Mar</td><td>150</td></tr>
+    </tbody>
+  </table>
+</figure>

package/recipes/confirm-action/contract.md

@@ -0,0 +1,28 @@
+# confirm-action — server response contract
+
+Purpose: confirm with the user before sending an htmx request.
+
+## Required client markup
+
+- `data-hx-{post|put|patch|delete}` — destructive method and URL.
+- `data-hx-trigger="hc:confirmed"` — wait for the confirm behavior to dispatch.
+- `data-hc-confirm` — confirm message shown in the shared dialog.
+- Optional `data-hx-target`, `data-hx-swap`.
+
+## Behavior flow
+
+1. User clicks the element.
+2. `hc.behaviors.js` intercepts the click and opens the shared confirm dialog.
+3. User confirms.
+4. Behavior dispatches `hc:confirmed` on the original element.
+5. htmx sends the request.
+
+## Server response
+
+- Return HTML for the target area; or
+- Return `HX-Trigger` with events such as `hc:toast`; or
+- Both.
+
+Status: any `2xx` for the swap and/or header. A non-2xx response is not
+swapped (htmx ≥ 2 default); note that `hc:confirmed` has already fired
+by then — the confirmation gates the *request*, not its outcome.

package/recipes/confirm-action/expanded.html

@@ -0,0 +1,17 @@
+<!-- Fully expanded HTML. -->
+<span class="hc-action">
+  <button
+    class="hc-button"
+    data-variant="error"
+    type="button"
+    data-hx-delete="/items/123"
+    data-hx-trigger="hc:confirmed"
+    data-hx-target="closest tr"
+    data-hx-swap="outerHTML"
+    data-hx-disabled-elt="this"
+    data-hx-indicator="closest .hc-action"
+    data-hc-confirm="Delete this item?">
+    Delete
+  </button>
+  <span class="hc-spinner htmx-indicator" aria-hidden="true"></span>
+</span>

package/recipes/confirm-action/recipe.html

@@ -0,0 +1,10 @@
+<!-- Short recommended usage. -->
+<button
+  class="hc-button"
+  data-variant="error"
+  data-hc-confirm="Delete this item?"
+  data-hx-delete="/items/123"
+  data-hx-trigger="hc:confirmed"
+  data-hx-target="closest tr">
+  Delete
+</button>

package/recipes/data-region/contract.md

@@ -0,0 +1,25 @@
+# data-region — server response contract
+
+Purpose: a named region the server can re-render on demand. Other parts of the page invalidate it by dispatching a domain event.
+
+## Required client markup
+
+- `<section id="..." class="hc-data-region">` with `data-hx-get` and `data-hx-swap="outerHTML"`.
+- `data-hx-trigger="load, <event>:<name> from:body"` — load on first render, refresh when an event fires anywhere on the body.
+
+## Invalidation pattern
+
+Other recipes (confirm-action, remote-dialog, …) can invalidate the region by returning an `HX-Trigger` header:
+
+```http
+HX-Trigger: {"items:changed":{}}
+```
+
+…or by dispatching the event from client behaviors after a local update.
+
+## Server response
+
+Return the complete `<section>` element (same id, same class, same attributes) so the swap is idempotent. Include an empty state when there are no rows.
+
+Status: `200 OK` with the fragment. A non-2xx response is not swapped
+(htmx ≥ 2 default), so the region keeps its previous rendering.

package/recipes/data-region/expanded.html

@@ -0,0 +1,17 @@
+<!-- Fully expanded HTML. -->
+<section
+  id="items"
+  class="hc-data-region"
+  data-hx-get="/items"
+  data-hx-trigger="load, items:changed from:body"
+  data-hx-swap="outerHTML"
+  data-hx-indicator="closest .hc-data-region"
+  aria-busy="false">
+  <header class="hc-data-region__header">
+    <h2>Items</h2>
+    <span class="hc-spinner htmx-indicator" aria-hidden="true"></span>
+  </header>
+
+  <!-- server-rendered list goes here -->
+  <ul class="hc-list"></ul>
+</section>

package/recipes/data-region/recipe.html

@@ -0,0 +1,9 @@
+<!-- Short recommended usage. A named region that the server can refresh. -->
+<section
+  id="items"
+  class="hc-data-region"
+  data-hx-get="/items"
+  data-hx-trigger="load, items:changed from:body"
+  data-hx-swap="outerHTML">
+  <!-- server-rendered list goes here -->
+</section>

package/recipes/datagrid-pager/contract.md

@@ -0,0 +1,73 @@
+# datagrid-pager — server response contract
+
+Purpose: paginate an `hc-datagrid` from the server with htmx. The grid is
+built for paged data — the server owns the data window; htmx swaps one
+page of rows; `installDatagrid()` re-initialises the swapped rows.
+
+## Required client markup
+
+- The grid's `<tbody class="hc-datagrid__body" id="rows">` is the swap
+  target, with `data-hx-target="#rows"` and **`data-hx-swap="innerHTML"`**.
+- The pager is an `hc-pagination` `<nav id="pager">`; each `.hc-pagination__item`
+  carries `data-hx-get="/…?page=N"`, `data-hx-target="#rows"`,
+  `data-hx-swap="innerHTML"`.
+- Optional status text (`#rows-status`, `aria-live="polite"`).
+
+## Why `innerHTML` (not `outerHTML`)
+
+`installDatagrid()` watches the **`<tbody>` element** for child changes.
+Swapping the rows *inside* the tbody (`innerHTML`) keeps that element, so
+the observer fires and the grid re-applies its roles, sticky offsets, and
+any resized column widths to the new rows. Replacing the whole `<tbody>`
+(`outerHTML`) would discard the observed node — avoid it.
+
+## Server response
+
+`GET /products?page=N&size=100` returns **only the page's rows** (the
+`innerHTML` of the tbody):
+
+```html
+<tr class="hc-datagrid__row">
+  <td class="hc-datagrid__cell" data-frozen><input type="checkbox" class="hc-checkbox" aria-label="Select row …"></td>
+  <th class="hc-datagrid__cell" data-frozen data-frozen-edge scope="row">101</th>
+  <td class="hc-datagrid__cell" data-col="name">…</td>
+  <td class="hc-datagrid__cell">$…</td>
+</tr>
+<!-- …one <tr> per row in the page… -->
+```
+
+Render each row with the **same column structure** as the header
+(`data-frozen` / `data-frozen-edge` on frozen cells, `data-col` on
+resizable/editable columns). Frozen-column `--hc-datagrid-left` offsets and
+resized widths are re-applied automatically after the swap — the server
+does not need to compute them per row.
+
+Status: `200 OK` with the rows (and the out-of-band pager/status
+fragments below). A non-2xx response is not swapped (htmx ≥ 2 default),
+so the current page stays — surface failures via an `HX-Trigger` toast.
+
+### Updating the pager and status (out-of-band)
+
+Return the new pager and status as out-of-band fragments in the same
+response so they update without a second request:
+
+```html
+<nav class="hc-pagination" id="pager" hx-swap-oob="true" aria-label="Pagination">
+  …items with aria-current="page" on the active page…
+</nav>
+<p id="rows-status" hx-swap-oob="true" aria-live="polite">101–200 / 5,000</p>
+```
+
+Mark the current page with `aria-current="page"`, and disable Prev/Next at
+the ends with `aria-disabled="true"`.
+
+## Notes
+
+- **Focus.** Swapping rows removes the previously active cell; the grid
+  resets a tabbable cell but does not move focus. Restore focus from the
+  server with `HX-Retarget` / an out-of-band focus target if needed.
+- **Selection** is per page unless the server re-renders selected rows with
+  `aria-selected="true"` (server-tracked selection across pages).
+- This recipe targets the standard one-`<tbody>` rows layout. For multi-row
+  records (`.hc-datagrid__record` tbodies) swap a wrapping region and let
+  the document-level observer re-initialise the grid.

package/recipes/datagrid-pager/expanded.html

@@ -0,0 +1,50 @@
+<!-- datagrid-pager — expanded form.
+     A frozen ID column, a status line ("X–Y / total"), and a prev/next +
+     numbered pager. The grid body and the pager + status are updated
+     together: rows swap into #rows (innerHTML); the pager and status are
+     returned as out-of-band fragments (hx-swap-oob) by the server. -->
+<div class="hc-datagrid" style="--hc-datagrid-max-height: 24rem;">
+  <div class="hc-datagrid__scroll">
+    <table class="hc-datagrid__table">
+      <thead class="hc-datagrid__head">
+        <tr>
+          <th class="hc-datagrid__headcell" data-frozen scope="col" style="--hc-datagrid-left:0;">
+            <input type="checkbox" class="hc-checkbox" aria-label="Select all">
+          </th>
+          <th class="hc-datagrid__headcell" data-frozen data-frozen-edge scope="col" style="--hc-datagrid-left:2.5rem;">ID</th>
+          <th class="hc-datagrid__headcell" data-resizable data-col="name" scope="col">Name</th>
+          <th class="hc-datagrid__headcell" scope="col">Unit price</th>
+        </tr>
+      </thead>
+
+      <!-- Swap target. Load the first page, then the pager drives it. -->
+      <tbody class="hc-datagrid__body" id="rows"
+             data-hx-get="/products?page=1&size=100" data-hx-trigger="load"
+             data-hx-target="#rows" data-hx-swap="innerHTML">
+        <!-- Server renders the page's rows here, e.g.:
+        <tr class="hc-datagrid__row">
+          <td class="hc-datagrid__cell" data-frozen style="--hc-datagrid-left:0;"><input type="checkbox" class="hc-checkbox" aria-label="Select row 1"></td>
+          <th class="hc-datagrid__cell" data-frozen data-frozen-edge scope="row" style="--hc-datagrid-left:2.5rem;">1</th>
+          <td class="hc-datagrid__cell" data-col="name">Chai</td>
+          <td class="hc-datagrid__cell">$18.00</td>
+        </tr>
+        -->
+      </tbody>
+    </table>
+  </div>
+
+  <div class="hc-cluster" style="justify-content: space-between;">
+    <p id="rows-status" aria-live="polite" style="margin:0;">1–100 / 5,000</p>
+
+    <nav class="hc-pagination" id="pager" aria-label="Pagination">
+      <a class="hc-pagination__item" data-hc-rel="prev" data-hx-get="/products?page=1&size=100"
+         data-hx-target="#rows" data-hx-swap="innerHTML" aria-disabled="true" href="?page=1">Prev</a>
+      <a class="hc-pagination__item" aria-current="page" data-hx-get="/products?page=1&size=100"
+         data-hx-target="#rows" data-hx-swap="innerHTML" href="?page=1">1</a>
+      <a class="hc-pagination__item" data-hx-get="/products?page=2&size=100"
+         data-hx-target="#rows" data-hx-swap="innerHTML" href="?page=2">2</a>
+      <a class="hc-pagination__item" data-hc-rel="next" data-hx-get="/products?page=2&size=100"
+         data-hx-target="#rows" data-hx-swap="innerHTML" href="?page=2">Next</a>
+    </nav>
+  </div>
+</div>