notid/integreat
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

refactor(ssr): full Selmer migration of Transaction Edit; remove the wizard

Browse Source 
Squashed Phase-2 SSR work: migrate the Transaction Edit modal's render path
entirely to Selmer templates (zero Hiccup in the render path), rip out the
multi-step wizard abstraction (EditWizard/LinksStep records, MultiStepFormState,
step-params[...] field names, mm/* middleware) in favor of a plain form with
flat derived state, and promote shared UI components to reusable Selmer partials
under resources/templates/components/. Adds the Selmer interop bridge, the
auto-ap.ssr.components.selmer (sc) wrapper library, and the ssr-form-migration
skill capturing the learnings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bryce
2026-06-24 08:23:34 -07:00
parent e2ccfc8d2c
commit 70c178de83
62 changed files with 3091 additions and 1006 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
.claude/skills/ssr-form-migration/SKILL.md Normal file
View File

@@ -0,0 +1,122 @@
---
name: ssr-form-migration
description: Migrate an SSR form or wizard modal to the whole-form HTMX swap doctrine, top-rooted render functions, the data-driven session-backed wizard engine, and (where it helps) Selmer templates. Use when simplifying a server-rendered form/wizard modal in this codebase, removing EDN-snapshot round-trips, deleting *-no-cursor* duplicate render fns, collapsing per-interaction routes, or replacing the multi-step wizard protocol machinery.
---
# SSR Form & Wizard Migration
A repeatable method for making a server-rendered form/wizard modal **simpler** without
changing user-facing behavior. Distilled from the first proven migration — the
`transaction/edit.clj` modal, which already runs on the whole-form `hx-select` swap
approach with **zero out-of-band swaps**. Every migration *reads this skill first* and
*extends it last* (the Growth contract below). If migration N+1 is not easier than N,
the skill-update step was skipped — treat that as a bug.
The four patterns every migration moves code toward live in `reference/`:
- `reference/swap-doctrine.md` — the four-rule HTMX swap priority order + the focus
invariant + Alpine-survives-swap hardening + target-selector strategy.
- `reference/render-functions.md` — one render fn per component, taking explicit data
**or a top-rooted cursor**; no faked cursor positions, no `*-no-cursor*` twins.
- `reference/form-vs-wizard.md` — single-step → plain form; multi-step → data-driven
engine with **per-step state in the Ring session** (the Django `formtools` model).
- `reference/selmer-conventions.md` — plain-HTML attributes via Selmer, the
Hiccup↔Selmer interop bridge, include/block patterns.
Growing cookbooks (append every migration):
`component-cookbook.md`, `gotchas.md`, `test-recipes.md`, `scorecard.md`.
---
## The per-migration playbook
Run this loop for each modal. The phase notes in the migration plan list only what is
*specific* to a modal; this loop is the constant.
1. **Read the skill.** Skim `reference/` and note which `component-cookbook.md`
entries and `gotchas.md` you can reuse. Start from the cookbook, not a blank file.
2. **Classify** (`reference/form-vs-wizard.md`).
- Single logical step (even with a `?mode=` toggle or add/remove rows) → **plain
form**: no server-side wizard state, no snapshot, no protocol.
- Genuinely multiple steps the user advances through → **wizard**: the data-driven
engine + per-step session storage.
- When in doubt, it's a form.
3. **Baseline the scorecard** (`scorecard.md`, heuristics in §6 of the plan). Record
before-numbers with cheap tools:
```bash
F=src/clj/auto_ap/ssr/<modal>.clj
wc -l $F # LOC (heuristic 4)
grep -c 'defn.*-no-cursor' $F # *-no-cursor* twins (heuristic 1)
grep -cE 'with-cursor|MapCursor\.' $F # faked cursor re-roots (heuristic 1)
grep -c 'hx-swap-oob' $F # OOB swaps (heuristic 7)
grep -cE '"hx-[a-z]' $F # mixed string hx- attrs (heuristic 8)
# route count: count this modal's entries in src/cljc/auto_ap/routes/*.cljc
```
4. **Characterize behavior (test-first).** Write or confirm a Playwright spec that
captures *current* behavior before you touch anything — focus/caret survival across
swaps, each field round-trip, validation errors, and the real save. This spec is the
parity contract; it must stay green through every commit. See `test-recipes.md`.
5. **Consolidate render functions** (`reference/render-functions.md`). Make each render
fn take explicit data or a **top-rooted cursor**. Delete `*-no-cursor*` duplicates
and any `with-cursor`/`MapCursor` rebind that fakes a deep starting position
(heuristics 1, 2). Using a cursor is fine; faking where it *starts* is not.
6. **Templatize in Selmer** (`reference/selmer-conventions.md`) where the component is
interactive/attribute-heavy. Reuse cookbook bits; add new ones back (heuristics 5, 8).
Static markup may stay Hiccup — Selmer scope is hybrid (Open decision 2).
7. **Wire HTMX per the swap doctrine** (`reference/swap-doctrine.md`). Keep the focus
invariant intact. No OOB except a genuinely disjoint region, documented (heuristic 7).
8. **Collapse routes** to 2 (`GET` open, `POST` submit) — `+1` for an add-row endpoint,
`+1` for the single `*-form-changed` whole-form re-render endpoint (heuristic 6).
9. **Verify.** Modal e2e green + full e2e suite at-or-above baseline; assert DB
mutations by querying Datomic, not markup; REPL-check the pure render/data fns.
Re-measure the scorecard — **no metric may regress for the touched modal** without a
written exception in `gotchas.md`.
10. **Commit** one reversible feature commit. The message includes the scorecard delta
and the reused/new cookbook entries.
11. **Feed the skill** (the Growth contract). *Not optional.*
---
## Growth contract — the last task of every migration
- Converted a component? → add its before/after to `component-cookbook.md`.
- Hit a surprise? → one entry in `gotchas.md`.
- Found a test pattern? → `test-recipes.md`.
- Playbook step missing or wrong? → fix this `SKILL.md`.
- Measured the scorecard? → append the row to `scorecard.md`.
**Success signal:** each migration reuses more cookbook entries and starts from a better
scorecard baseline than the previous one.
---
## Non-negotiables
- **Focus invariant:** the input the user is typing in is *never* inside the region its
own request swaps. Violating this drops the caret. (Proven by the
`transaction-edit-swap.spec.ts` caret tests.)
- **No new OOB swaps.** If tempted to OOB something inside the same feature, restructure
the DOM so the dependent element shares an ancestor with the trigger and use an
ordinary swap (e.g. totals in a sibling `<tbody>`).
- **Behavior parity is proven by tests, not by reading.** The full e2e suite stays green
after every migration.
- **Don't game the heuristics.** They're directional evidence paired with the e2e parity
gate; review the trend, not single numbers.
## Project conventions that bite (see `gotchas.md`)
- Edit Clojure with the clojure-mcp tools (`clojure_edit`, `clojure_edit_replace_sexp`),
not the raw file editor. `clj-paren-repair` then `lein cljfmt fix` when a file won't
compile.
- Run tests via the `clojure-eval` skill / `clj-nrepl-eval -p PORT`, not `lein test`.
- Temp files go in `./tmp/`.

182
.claude/skills/ssr-form-migration/reference/component-cookbook.md Normal file
View File

@@ -0,0 +1,182 @@
# Component cookbook
GROWS every migration. Each entry: what it is, the swap rule it uses, and the canonical
snippet. Reuse these before writing anything new; the success signal is *more reuse each
migration*.
Seeded from `transaction/edit.clj` (Hiccup form — Selmer versions land in Phase 2).
---
## typeahead (account / vendor) — Alpine + tippy, survives swaps
Used for account and vendor selection. Click-to-select (not a live text caret), so a
whole-form swap on change is safe. Null-guard `tippy?`/`$refs.input?`.
```clojure
(defn account-typeahead* [{:keys [name value client-id x-model]}]
[:div.flex.flex-col
(com/typeahead {:name name
:placeholder "Search..."
:url (hu/url (bidi/path-for ssr-routes/only-routes :account-search)
(cond-> {:purpose "transaction"} client-id (assoc :client-id client-id)))
:id name
:x-model x-model ; binds selected value into the row's Alpine scope
:value value
:content-fn (fn [v] (:account/name (d-accounts/clientize ... v client-id)))})])
```
Reuse note: `:x-model` lets the *parent* row read the selected id (e.g. `accountId`) to
gate a targeted location swap. See account-row.
## account-row — cursor render fn + per-row targeted location swap + whole-form remove
The canonical "row in a repeated grid" pattern. One render fn, top-rooted cursor.
- account typeahead binds `accountId` into row Alpine scope;
- **location cell** swaps *only itself* (`#account-location-<index>`) on `changed`
(swap-doctrine Rule 2);
- **amount cell** swaps *only* `#account-totals` (Rule 4, sibling tbody);
- **remove** swaps the whole form (Rule 3).
```clojure
(defn transaction-account-row* [{:keys [value client-id amount-mode index]}]
(com/data-grid-row
(-> {:class "account-row" :id (str "account-row-" index)
:x-data (hx/json {:show ... :accountId (fc/field-value (:transaction-account/account value))})
:data-key "show" :x-ref "p"}
hx/alpine-mount-then-appear)
(fc/with-field :db/id (com/hidden {:name (fc/field-name) :value (fc/field-value)}))
(fc/with-field :transaction-account/account
(com/data-grid-cell {} (com/validated-field {:errors (fc/field-errors)}
(account-typeahead* {:value (fc/field-value) :client-id client-id
:name (fc/field-name) :x-model "accountId"}))))
(fc/with-field :transaction-account/location
(com/data-grid-cell {:id (str "account-location-" index)} ...Rule 2 targeted swap...))
(fc/with-field :transaction-account/amount
(com/data-grid-cell {} ...Rule 4 totals swap...))
(com/data-grid-cell {:class "align-top"} ...Rule 3 whole-form remove...)))
```
TODO Phase 2: drop the `transaction-account-row-no-cursor*` twin; this is the only kept form.
## totals in a sibling `<tbody>` — Rule 4 instead of OOB
Running totals live in their own `<tbody id="account-totals">`, a sibling of the
input-bearing rows, so an amount edit refreshes them with a plain targeted swap and never
replaces the amount input (caret survives).
```clojure
(com/data-grid
{:footer-tbody
[:tbody {:id "account-totals"}
(com/data-grid-row {:class "account-total-row"} ... (account-total* request) ...)
(com/data-grid-row {:class "account-balance-row"} ... (account-balance* request) ...)]}
...input rows...)
```
## money-input / text-input amount field — Rule 4 targeted totals swap
```clojure
(com/money-input
{:name (fc/field-name) :id (str "account-amount-" index) :class "w-16 account-amount-field"
:hx-post (bidi/path-for ssr-routes/only-routes ::route/edit-form-changed)
:hx-target "#account-totals" :hx-select "#account-totals" :hx-swap "outerHTML"
:hx-trigger "keyup changed delay:300ms" :hx-include "closest form"})
```
`%` mode swaps to `com/text-input {:type "number" :step "0.01"}` with the same swap attrs.
## memo field — Rule 1, no request
```clojure
(com/text-input {:value (fc/field-value) :name (fc/field-name) :id "edit-memo"
:placeholder "Optional note"}) ; no hx-* — rides along to save
```
## location-select — first Selmer-migrated component (validated)
The account row's location `<select>`, rendered from a Selmer template instead of
`com/select`. The first interactive modal component off Hiccup; proves the render-file
path + interop bridge on real, e2e-covered markup (swap 6/6, transaction-edit 8/8).
```clojure
;; templates/components/location-select.html — plain HTML, {% for %} + {% if selected %}
(defn location-select* [{:keys [name client-locations value ...]}]
(let [options (cond ...) ; [[value label] ...]
selected (or value (ffirst options))
classes (str/join " " (conj (vec inputs/default-input-classes) "w-full"))]
(sel/render->hiccup "templates/components/location-select.html"
{:name name :classes classes
:options (for [[v l] options] {:value v :label l :selected (= v selected)})})))
```
Reuse: pass `inputs/default-input-classes` in (don't hard-code); embed via
`render->hiccup` so it drops into the still-Hiccup row. See `selmer-conventions.md`.
## fixed-index row from explicit data — de-faking a deep cursor
When a row always lives at a known index (e.g. simple mode renders exactly `accounts[0]`),
render it from **explicit data with explicit field names** instead of faking a cursor
rooted there. Build the name the same way the cursor would (`path->name2`) and read errors
from the same path — no `with-cursor`/`MapCursor` rebind, no `with-field-default` (which
*mutates* the cursor and breaks swap behavior, see `gotchas.md`).
```clojure
(defn- account-field-name [index field] ; == path->name2 for this path
(str "step-params[transaction/accounts][" index "]["
(if (keyword? field)
(str (when (namespace field) (str (namespace field) "/")) (name field))
field) "]"))
(defn- account-field-errors [index field]
(when (bound? #'fc/*form-errors*)
(get-in fc/*form-errors* [:step-params :transaction/accounts index field])))
;; render the row directly -- no fc/with-field / fc/with-cursor wrappers
[:span
(com/hidden {:name (account-field-name 0 :db/id) :value row-id})
(com/validated-field {:errors (account-field-errors 0 :transaction-account/account)}
(account-typeahead* {:name (account-field-name 0 :transaction-account/account) ...}))
...]
```
Verify byte-parity against the cursor version (the swap spec's simple-mode tests catch
divergence). Scorecard heuristic 1: faked roots → 0.
## mode toggle ($/% radio, simple/advanced link) — Rule 3, whole-form swap
```clojure
(com/radio-card {:options [{:value "$" :content "$"} {:value "%" :content "%"}]
:value amount-mode :name "step-params[amount-mode]"
:hx-post (bidi/path-for ssr-routes/only-routes ::route/toggle-amount-mode)
:hx-target "#wizard-form" :hx-select "#wizard-form" :hx-swap "outerHTML"
:hx-include "closest form"})
```
TODO Phase 2: the simple/advanced toggle becomes a `?mode=` re-render (plain form), not a
dedicated route.
---
## The Selmer component library (`auto-ap.ssr.components.selmer` / `sc`) — Phase 2-final
Every shared component the modal renders through is now a thin Clojure wrapper over a
partial under `resources/templates/components/`. **Reuse these before reaching for the
Hiccup `com/*` versions in a migrated modal.** Each wrapper builds a context (reusing the
real class helpers so output matches modulo Tailwind order) and renders its own partial via
the interop bridge; dynamic HTMX/Alpine attrs go through `sc/attrs->str` →
`{{ attrs|safe }}`. See `selmer-conventions.md` for the mechanics.
| Wrapper | Partial | Notes |
|---------|---------|-------|
| `sc/hidden` / `sc/text-input` / `sc/money-input` | `hidden`/`text-input`/`money-input`.html | leaf inputs; class via `inputs/default-input-classes` + `use-size` |
| `sc/validated-field` | `validated-field.html` | label + body + always-present error `<p>`; pass-through attrs land on the wrapping div (the per-row location cell hangs its swap wiring here) |
| `sc/button` / `sc/a-button` / `sc/a-icon-button` | `button`/`a-button`/`a-icon-button`.html | spinner via `{% include "spinner.html" %}`; class via `btn/bg-colors` |
| `sc/badge` / `sc/link` | `badge`/`link`.html | |
| `sc/button-group` / `sc/button-group-button` | `button-group(+button).html` | the group does **not** mutate children's classes (the Hiccup `group-` added rounded-l/r) — add rounding in the caller/template (tabs do) |
| `sc/radio-card` | `radio-card.html` | reproduces the `select-keys [:hx-post :hx-target :hx-swap :hx-include :hx-trigger]` filter (drops `:hx-vals`/`:hx-select`) **and** the dangling-`[:h3]` quirk: only the `<ul>` renders |
| `sc/data-grid` (+ `-header`/`-row`/`-cell`) | `data-grid*.html` | table shell + optional `footer-tbody` (the swappable totals tbody) |
| `sc/typeahead` | `typeahead.html` | full Alpine + tippy; resolves `{value,label}` server-side via `content-fn`; every `tippy?.` null-guard preserved; hidden posting `<input>` with `:value="value.value"` + the `x-init` watcher |
| `sc/modal` | `modal.html` | the `@click.outside="open=false"` wrapper |
| SVGs | `spinner`/`svg-x`/`svg-external-link`/`svg-drop-down`.html | static, `{% include %}`d so the markup isn't duplicated |
Modal-specific structure lives under `resources/templates/transaction-edit/`
(`edit-form`, `edit-modal`, `links-body`, `manual-coding`, `simple-mode`, `account-totals`,
`details-panel`, the four match panels, `transitioner`). The render fns in `edit.clj`
gather data, call `sc/*`, and interpolate the fragments into these layout templates as
`{{ frag|safe }}`. **Verify each wrapper by class-set equality + e2e, never byte-parity**
(`hh/add-class` is set-based, so class order differs from the Hiccup output).

146
.claude/skills/ssr-form-migration/reference/form-vs-wizard.md Normal file
View File

@@ -0,0 +1,146 @@
# Forms vs. wizards (and the data-driven wizard engine)
## Classify first
| Signal | Classification |
|--------|----------------|
| One logical step — even with a `?mode=` toggle, $/% radio, or add/remove rows | **plain form** |
| The user genuinely advances through ordered steps, each validated before the next | **wizard** |
| In doubt | **form** |
Most "wizards" in this codebase are single-step forms wearing wizard costumes: they
implement the multi-step protocol (`mm/ModalWizardStep` + friends), serialize an EDN
snapshot into hidden fields, and register 10–20 stacked-middleware routes — all for one
step. That is pure overhead to delete.
> **Done — Transaction Edit is now a plain form.** `LinksStep`/`EditWizard` and all `mm/*`
> usage were deleted from `transaction/edit.clj`; the worked example below is realized, not
> aspirational. See "Single-step → plain form (realized)".
## The machinery being replaced
The old shape (kept here as the "before"):
```clojure
(defrecord LinksStep [linear-wizard]
mm/ModalWizardStep
(step-name [_] "Transaction Actions")
(step-key [_] :links)
(edit-path [_ _] [])
(step-schema [_] (mm/form-schema linear-wizard))
(render-step [this {{:keys [snapshot step-params]} :multi-form-state :as request}] ...))
```
…plus the snapshot round-trip: the whole accumulating form state is serialized to hidden
fields (custom EDN readers), then rebuilt every request by merging the posted pieces back
into the snapshot (`:multi-form-state :snapshot` is read ~75× in `edit.clj`). The
serialization needs custom readers, the merge is error-prone, and the payload grows each
step.
---
## Single-step → plain form
Two routes: `GET` (render) and `POST` (validate + save). State is plain form fields + an
entity id. No snapshot, no server state, no protocol.
```clojure
{::route/edit (fn [req] (html-response (render-edit-form {:entity (get-entity req)})))
::route/edit-submit (fn [req] (validate-and-save req))}
```
A `?mode=` toggle is just the `GET` re-rendering with a different query param — still a
plain form. An add-row interaction is one extra `POST` that appends a fresh row and
re-renders (the `+1` route).
### Single-step → plain form (realized: Transaction Edit)
What replacing the wizard actually looked like, end to end:
1. **Delete the records + middleware.** `EditWizard`/`LinksStep`, `mm/open-wizard-handler`,
`mm/next-handler`, `mm/submit-handler`, `mm/wrap-wizard`, `mm/wrap-decode-multi-form-state`,
and the `edit-wizard-navigate` route all go. `render-step` becomes a plain `render-form`.
2. **Rename the fields off `step-params[...]`.** Field names are now the schema path
directly (`(path->name2 :transaction/accounts 0 :transaction-account/account)` →
`transaction/accounts[0][transaction-account/account]`). They decode straight into the
form schema via the unchanged `wrap-nested-form-params` + `mc/decode` — no two-key
snapshot/step-params decode. **Strip stray keys after decode** (`select-keys` to the
schema's keys) or a non-schema input like the tab group's `method` hidden 500s the save
(see `gotchas.md`).
3. **Flat state.** `wrap-derive-state` builds a plain `{:snapshot :edit-path :step-params}`
map (not the `MultiStepFormState` record): `entity-only` fields from the entity, editable
fields from the live posted form (absent = cleared). The ~34 `:snapshot` reads keep
working.
4. **Validation/error flow without `wrap-ensure-step`.** Reuse the generic
`wrap-form-4xx-2` directly: `(-> submit-edit (wrap-form-4xx-2 render-form-response) …)`.
`submit-edit` runs `assert-schema` then dispatches the save; on a throw, `wrap-form-4xx-2`
re-renders the whole form with `:form-errors` keyed by schema paths. A `*errors*` dynamic
var (bound by `render-form`) replaces the form-cursor's `*form-errors*` for field lookups.
5. **Routes shrink to** `edit-wizard` (GET open), `edit-submit` (POST), `edit-form-changed`
(POST whole-form re-render for dependent changes), `location-select` (GET),
`unlink-payment` (POST).
---
## Genuinely multi-step → data-driven engine with session-stored step state
> **Inspiration — Django `formtools` `WizardView`.** Django's wizard does *not* round-trip
> a serialized blob of the whole form through the page. Each step's validated data is
> written to a **storage backend (the user session by default)** under that step's key,
> and the steps are combined only at the very end via `get_all_cleaned_data()`. We adopt
> the same model: **replace the EDN snapshot + piecewise merging with per-step form state
> stored in the Ring session.** A step writes its own data under its own key; nothing is
> merged into a snapshot and nothing about other steps rides through the form.
> Refs: `formtools.wizard.views.WizardView`, `SessionStorage`, `get_all_cleaned_data()`
> (https://django-formtools.readthedocs.io/en/latest/wizard.html).
A wizard is **data**:
```clojure
(def vendor-wizard-config
{:steps [{:key :info :schema info-schema :fields [...] :render render-info-step
:next (fn [data] :terms)}
{:key :terms :schema terms-schema :fields [...] :render render-terms-step
:next (fn [data] :done)}]
:init-fn (fn [req] {...})
:submit-route "/admin/vendor/wizard/submit"
:done-fn (fn [all-data req] (save! all-data) (html-response "Saved"))})
```
with a tiny engine (no protocols) whose state lives **in the session**, keyed by a wizard
instance id, each step's data under its own step key — the formtools `SessionStorage`
model. No snapshot, no custom EDN readers, no merge-into-snapshot:
```clojure
;; Storage backed by the Ring session. Path: [:wizards <wizard-id> :step-data <step-key>]
(defn create-wizard! [session config]
(let [id (str (java.util.UUID/randomUUID))]
[id (assoc-in session [:wizards id]
{:current-step (-> config :steps first :key) :step-data {}})]))
(defn put-step [session id k data] (assoc-in session [:wizards id :step-data k] data)) ; replace, not merge
(defn set-step [session id k] (assoc-in session [:wizards id :current-step] k))
(defn get-all [session id] (->> (get-in session [:wizards id :step-data]) vals (apply merge)))
(defn forget [session id] (update session :wizards dissoc id))
```
The render emits only a **reference token** (`wizard-id`, `current-step`) in the form —
never the form's state. The submit handler validates the posted step, `put-step`s it,
computes `:next`, and either advances (`set-step`) or finishes (`get-all` + `:done-fn` +
`forget`). Every fn returns the updated session for the handler to thread into the Ring
response (`(assoc resp :session session')`).
**Two routes per wizard:** open (`partial open-wizard config`) and submit
(`partial handle-step-submit config`). State is namespaced by `wizard-id` inside the
session, so multiple in-flight wizards (and browser tabs) don't collide, and it is
discarded on completion (`forget`).
### Storage lifetime (Open decision 1)
State lives in the Ring session, scoped to true multi-step wizards (plain forms hold
none). Lifetime follows the session; `forget` on completion prevents session bloat. For
long-lived wizards, confirm the session backend (in-memory vs. durable) is acceptable or
pick a durable store. **This engine is built in Phase 6** (Transaction Rule) — until then
this file describes the target; validate `components/wizard_state.clj` +
`components/wizard2.clj` against it when they land, and update this doc from the real
implementation.

207
.claude/skills/ssr-form-migration/reference/gotchas.md Normal file
View File

@@ -0,0 +1,207 @@
# Gotchas
GROWS every migration. One entry per surprise. Also the home for any **written exception**
to the scorecard ratchet (a metric that regressed for a documented reason).
---
## Stale `$refs` / `tippy` after a swap
A whole-form swap can run an Alpine event handler *before* the component re-initialises,
so a handler that dereferences `$refs.input.__x_tippy` or calls `tippy.show()` throws.
**Always null-guard:** `$refs.input?.__x_tippy?.hide()`, `tippy?.show()`. The
`transaction-edit-swap.spec.ts` `trackErrors()` helper fails the test on any `pageerror`
or `console.error`, which is exactly how a stale-ref throw surfaces.
## Let the server value win — don't preserve Alpine state across a server-driven change
When a server change should update a component (e.g. choosing a vendor sets its default
account), rebuild that section fresh on the swap so the server-provided value lands
without keying tricks. The bug this prevents: "changing the vendor a *second* time doesn't
update the account" because preserved Alpine state shadowed the new server value. If you
*must* preserve a component, key it by value so a change forces re-init:
`(assoc attrs :key (str id "--" current-value))`.
## Focus dies if the typed input is inside its own swapped region
The single most important invariant. Amount field → swap a sibling tbody, not the row.
Memo → swap nothing. If a caret test (`sameNode`) fails, the input is in its own swap
region — re-target to a sibling/ancestor that excludes it.
## Faked cursors breed duplicate render fns
A `with-cursor`/`MapCursor` re-root to fake a deep start forces a `*-no-cursor*` twin.
Removing the fake lets you delete the twin. Don't "fix" a faked cursor in place — top-root
it and collapse to one render fn. (See `render-functions.md`.)
## Edit Clojure with clojure-mcp tools, not the file editor
`clojure_edit` / `clojure_edit_replace_sexp`. If a file won't compile: `clj-paren-repair`
the file, then retry; if still broken, `lein cljfmt check`. Run tests via `clojure-eval` /
`clj-nrepl-eval -p PORT`, never `lein test` (slow, last resort).
## Solr/typeahead in tests
Account/vendor search is backed by Solr, unavailable in tests. To drive a typeahead in
e2e: type under the 3-char threshold, then inject a result into Alpine state
(`Alpine.$data(el).elements = [{value, label}]`) and click it — the real click handler,
`tippy.hide()`, Alpine reactivity, and the HTMX swap all run as in production. Entity ids
come from `GET /test-info`.
---
## UI-only control fields must be stripped before a Datomic upsert
The wizard snapshot/step-params carry UI control fields that are **not** schema
attributes — `:action`, `:amount-mode`, and (added by the simple/advanced work) `:mode`.
The `:manual` save handler stripped `:action`/`:amount-mode` but not `:mode`, so every
*advanced* manual save passed `:mode "advanced"` into `:upsert-transaction` and 500'd with
`:db.error/not-an-entity :mode`. Lesson: when a save derives its tx-data from the form
snapshot, **strip every non-schema control key** before transacting. The session-backed
wizard engine (Phase 6) avoids this class of bug by storing per-step *validated* data
only — UI control fields never enter the combined data. This was a real production bug
surfaced by the e2e gate, not a test artifact.
## E2E helpers must use the Alpine **v3** API, not the v2 `__x` internal
The app loads Alpine v3 (`cdn.jsdelivr.net/npm/alpinejs@3.x.x`). The v2 internal
`el.__x.$data` is **gone** — `el.__x` is `undefined`, so any helper that pokes it silently
no-ops. A stale `selectAccountFromTypeahead` did this and left the posted account empty
(account-controlled by `x-model`, so the raw DOM `.value` you set is overwritten from
Alpine's empty state). Drive components the real way instead: `window.Alpine.$data(el)`,
open the tippy dropdown, inject `elements`, click the result — exactly as
`transaction-edit-swap.spec.ts` does. Probe with
`{ hasLegacy__x: !!el.__x, hasAlpineData: !!window.Alpine.$data(el) }`.
## Diagnosing a "modal won't close after save"
The edit modal closes on an `hx-trigger: modalclose` from a *successful* save; a
validation failure re-renders the `#wizard-form` (200), and a server exception returns 500
(caught by `wrap-error`). To find which: capture POST responses in Playwright
(`page.on('response', …)`), read the `edit-submit` body — a `<form id="wizard-form">` means
validation re-render; a `#error {…}` stack means a 500. Then serialize the form right
before save (`new FormData(document.querySelector('#wizard-form'))`) to see exactly what
posts. This is how the `:mode` 500 and the empty-account bugs above were isolated.
## De-faking a cursor is not a drop-in — `with-field-default` mutates
Tempting fix for a faked deep cursor (`with-cursor` + synthetic `MapCursor` at index 0):
replace it with `(fc/with-field-default 0 {})` to advance naturally. **It broke the
simple-mode swap** (`transaction-edit-swap` test 1 threw). `with-field-default` calls
`cursor/transact!` — it *mutates the form cursor* (assoc-ing the default row) as a render
side effect, which changes simple-mode behavior. The read-only synthetic `MapCursor` did
not. Lesson: removing a faked cursor on these modals is **not** a one-liner — it's part of
the larger render-fn extraction (render the row from explicit data, construct field names
directly, look up errors explicitly), done when the simple/advanced rows are reworked into
pure render fns / Selmer. Don't swap one cursor primitive for another and assume parity;
verify against the swap spec, and expect the de-fake to come with the render-fn rewrite.
## Snapshot operations read stale state and drop live form values (heuristic 2)
The whole-form operation handlers (`apply-new-account`, `apply-remove-account`,
`apply-toggle-amount-mode`) rebuild the account rows from the **decoded `:snapshot`** (the
hidden EDN field), not from the live posted `:step-params`. So any value the user has typed
but that hasn't been re-serialised into the snapshot yet — e.g. an amount typed right
before clicking "New account" — is **silently lost** when the operation re-renders. This is
the snapshot round-trip fragility the migration removes (heuristic 2: → 0 merges; state
should ride in the form, not a parallel snapshot). It bit the percentage-split e2e: typing
50% then adding a row reverted the first row to its snapshot value, yielding a 66.67/33.33
split. Two ways it shows up and how to handle until the snapshot is gone:
**Fixed (Stage 1):** the operation handlers read the live `:step-params` rows (already
schema-decoded by `mm/wrap-wizard`) so typed values survive add/remove/toggle.
**Done (Stage 2 — the snapshot round-trip is gone).** The EDN `snapshot` hidden field +
custom readers + `merge-multi-form-state` are removed. A `db/id` hidden rides in the form;
`wrap-derive-state` rebuilds `:multi-form-state` per request from `entity ∪ step-params`,
and `EditWizard.render-wizard` renders a plain form (no snapshot/edit-path/current-step
hiddens). The ~34 `:snapshot` reads still work — `:snapshot` is now a derived map, not a
round-tripped blob.
**Trap that cost hours — derive `entity ∪ step-params` correctly.** First cut was
`(merge base step-params)`. Bug: `base` always carries the entity's *persisted* accounts,
so after the user removes every row (step-params has no accounts key) the merge falls back
to base → the persisted accounts **resurrect** on the next operation. Fix: editable fields
(accounts, vendor, memo, approval, action, mode, amount-mode) come **only** from the live
form (absent = cleared); only entity-only fields (`db/id`, client, amount, description,
status, type) come from the entity. Lesson: with a posted form, "field absent" means
*cleared*, not "use the persisted value" — never merge the entity's editable fields back in.
**Verify the snapshot removal on a FRESH server, and don't trust a long-lived in-process
test server.** Protocol/defrecord (`EditWizard.render-wizard`) and middleware reloads do
**not** fully take in a running REPL — the server kept rendering the old snapshot field
after `:reload`, and an in-process server that isn't reseeded between `npx playwright`
invocations accumulates state that makes order-dependent tests flake. Both produced hours
of phantom failures. Restart the REPL clean (or reseed) before trusting an e2e result; CI
boots a fresh server per run, so the fresh-server number (38 pass / 1 unrelated) is the real one.
## Characterization tests rot against table order and removed wizard chrome
Two stale-test traps surfaced once the masking failure was fixed (a `mode: 'serial'` file
hides every test after the first failure, so fixing one unmasks the next):
- **Hard-coded amounts per table row index** (`openEditModal(page, 3)` then
`expect(amount).toBeCloseTo(400)`) break because same-date seed transactions have no
pinned row order. Read the actual value (e.g. the grid's `.account-grand-total-row`)
instead of hard-coding.
- **Helpers that navigate the old multi-step wizard** (`click('button:has-text("Transaction
Actions")')`) hang once the modal is single-page. Drop the navigation; the action tabs
are present immediately.
## Flat decode leaks stray form fields into the saved entity (the `method` 500)
Dropping the wizard's `step-params[...]` field-name prefix and decoding posted params
**straight into the form schema** means the decode now captures **every** posted field, not
just the namespaced ones. A single stray field breaks the save:
- The tab switcher is `(com/button-group {:name "method"} …)`, which emits
`<input type="hidden" name="method">`. Under the wizard, `method` lived *outside*
`step-params[...]` so it never entered the decoded map. After the rename it decodes to
`:method ""` (malli `:map` is open and passes unknown keys), rides into `snapshot` →
`tx-data`, and `:upsert-transaction` rejects it → **HTTP 500 on save**.
- Symptom: the save POST fires (confirm with a `println` in the submit handler) but the
modal never closes, because the 500 trips `htmx:response-error`. The server error may go
to mulog, not stdout — an empty stdout log does **not** mean "no error." Reproduce the
exact POST with `curl` (add/remove one field) to isolate the offender fast.
**Fix:** strip the decoded map to the schema's known top-level keys before threading on
(`select-keys decoded edit-form-keys`); keep that allowlist next to the schema. Nested
account sub-maps decode fine — only the top level needs the guard.
## REPL reload does not refresh a running jetty's routes — restart the JVM
`handler/match->handler-lookup` is a top-level `def` capturing `(merge ssr/key->handler …)`
at load, through a chain of module-level `def`s (`edit` → `ssr.transaction` → `ssr.core` →
`handler`). Reloading the leaf `edit.clj` updates it but **not** the captured merges, and a
jetty started `(run-jetty app …)` holds a static `app` that doesn't re-deref the lookup per
request. Net: after a handler/route/record change, an already-running dev server keeps
serving the **old** code — `curl` shows the pre-change response (e.g. the old wizard
transitioner) while your REPL renders the new one. **Restart in a fresh JVM** for
route/record/middleware changes. For e2e, the Playwright test server
(`lein run -m auto-ap.test-server`) is a fresh JVM compiling from disk — but kill any stale
`:3333` first (`reuseExistingServer` reuses it), and kill **by port**
(`ss -tlnp | grep :3333`), never `pkill -f test-server` (it matches its own command line).
## Full-suite e2e flakes are shared-seed interference
The test server seeds once at boot; edit tests **save** (mutate) those seed transactions.
Run in parallel, workers race the same rows and earlier saves pollute later reads → phantom
failures that pass in isolation.
**Proper fix (landed on `staging`, adopted at the rebase):** a `/test-reset` endpoint
(`test_server.clj` → `reset-test-data!` recreates + re-seeds the in-memory db) called from a
`test.beforeEach` in each spec, plus `fullyParallel: false` + `workers: 1` in
`playwright.config.ts`. Every test starts from the same deterministic dataset regardless of
run order. This **supersedes** the earlier `--workers=1`-only workaround (which kept order
dependence; it merely serialized the races instead of eliminating cross-test state).
Post-adoption baseline is **39 pass / 0 fail** — the previously-flaky
`transaction-navigation.spec.ts` date-range test is now green, because `/test-reset` removes
the residual mutation it was tripping over.
## Scorecard exceptions (ratchet violations with a reason)
**Heuristic 9 (Hiccup in render path) — partial exception (Phase 2-final).** The post-save
`com/success-modal` confirmation dialogs in `save-handler` keep ~6 `[:p …]` Hiccup lines.
They are terminal responses (shown after the form closes), reuse a shared dialog component,
and sit outside the form's interactive render path. Migrating them means porting the shared
`success-modal` to Selmer — a Phase 11 cross-cutting task, not a single-modal one.

85
.claude/skills/ssr-form-migration/reference/render-functions.md Normal file
View File

@@ -0,0 +1,85 @@
# Render functions: explicit data, or a top-rooted cursor
**One function, data in, markup out.** The data can arrive as a plain map *or* via a
cursor — as long as the cursor was rooted at the top of the form and walked down to here,
never faked to start at this depth. The rule is about *where the cursor starts*, not
whether you use one.
## GOOD — explicit data, pure, testable without setup
```clojure
(defn account-row [{:keys [account index client-id amount-mode]}]
(com/data-grid-row
(com/hidden {:name (str "accounts[" index "][db/id]")
:value (or (:db/id account) "")})
(com/data-grid-cell
(account-typeahead* {:value (:transaction-account/account account)
:name (str "accounts[" index "][account]")
:client-id client-id}))
...))
```
## ALSO FINE — a cursor that started at the form root and was advanced naturally
```clojure
;; The top-level render walks the cursor; the row fn receives the dereferenced row
;; (or the advanced cursor). No rebinding of *current*/*prefix* to fake depth.
(defn account-rows [accounts-cursor]
(for [row-cursor (fc/each accounts-cursor)] ; advanced from the root, not faked
(account-row {:account @row-cursor :index (fc/index row-cursor) ...})))
```
`transaction/edit.clj`'s `transaction-account-row*` is the cursor form done right: the
caller (`account-grid-body*`) holds a top-rooted cursor via `fc/cursor-map` and hands each
row cursor to one render fn.
---
## The SMELL this migration removes
### 1. Faking the cursor's starting position
A "form cursor" is fine. The pain is **rebinding the dynamic root deeper in the tree** so
a deeply nested render fn can run against a fragment. Real example from
`transaction/edit.clj`'s `simple-mode-fields*` (the thing to delete):
```clojure
;; SMELL: re-roots the cursor to a synthetic MapCursor pointed at accounts[0] so a
;; fragment can render "deep". Fragile, and the source of the *-no-cursor* twin below.
(fc/with-field :transaction/accounts
(fc/with-cursor (let [cur fc/*current*]
(if (sequential? @cur)
(nth cur 0 nil)
(auto_ap.cursor.MapCursor. {} (cursor/state cur)
(conj (cursor/path cur) 0))))
...))
```
Target: the cursor begins at the top level of what the form consumes and walks down
naturally. Because the **whole form is re-rendered each time** (swap doctrine), there is
no longer any reason to fake a deep starting position.
### 2. The `*-no-cursor*` twin
Faking the deep cursor forces a *second copy of the same markup* — one that reads the
faked cursor and one that takes plain params for the cases where the fake can't be set up.
`transaction/edit.clj` has exactly this pair:
```clojure
(defn transaction-account-row* [{:keys [value index client-id ...]}] ...) ; cursor form
(defn transaction-account-row-no-cursor* [{:keys [account index client-id ...]}] ...) ; duplicate markup
```
**Fix:** keep one render fn. If a caller already holds a top-rooted cursor, advance it and
hand the row data (or the advanced cursor) to that one fn. Delete the `*-no-cursor*` copy.
Heuristic 1 targets `grep -c 'defn.*-no-cursor'` → 0 and faked-cursor re-roots → 0.
## Scorecard hooks (heuristics 1, 2)
```bash
grep -c 'defn.*-no-cursor' $F # → 0
grep -cE 'with-cursor|MapCursor\.' $F # faked re-roots → 0 (top-rooted cursors are fine)
```
Top-rooted cursors do **not** count against heuristic 1 — only *re-roots that fake depth*
and the `*-no-cursor*` twins do.

84
.claude/skills/ssr-form-migration/reference/scorecard.md Normal file
View File

@@ -0,0 +1,84 @@
# Quality scorecard (the ratchet)
Cheap to measure (`grep -c`, `wc -l`, `clj-kondo`), recorded **before/after each
migration** in the commit message and in the results table below. **No metric may regress
for the touched modal** without a written exception in `gotchas.md`. These are directional
evidence, not targets to game — always paired with the e2e parity gate.
## Heuristics
| # | Heuristic | Measure | Target |
|---|-----------|---------|--------|
| 1 | Faked cursor positions (not cursors themselves) | `grep -cE 'with-cursor\|MapCursor\.'` re-roots + `grep -c 'defn.*-no-cursor'` | → 0 (top-rooted cursors are fine) |
| 2 | Implicit state merges (snapshot/cursor) | count merge sites | → 0 (forms); explicit `put-step` only (wizards) |
| 3 | Branching complexity | `clj-kondo`, or count `cond`/`condp`/`case`/nested `if` + max depth | net ↓ |
| 4 | Lines of code | `wc -l` on the modal's file(s) | net ↓ |
| 5 | Reuse / cross-form similarity | cookbook components reused; duplicated-block count | reuse ↑, dup ↓ |
| 6 | Route count | count routes for the modal | → 2 (+1 for add-row) |
| 7 | OOB swaps | `grep -c hx-swap-oob` | → 0 unless a justified disjoint-region case is documented |
| 8 | Attribute consistency | mixed `:x-`/`"x-"` encodings in migrated template | → 0 |
## How to measure (copy/paste)
```bash
F=src/clj/auto_ap/ssr/<modal>.clj
echo "LOC $(wc -l < $F)"
echo "no-cursor twins $(grep -c 'defn.*-no-cursor' $F)"
echo "faked-cursor roots $(grep -cE 'with-cursor|MapCursor\.' $F)"
echo "snapshot merges $(grep -c ':multi-form-state :snapshot' $F)"
echo "branch forms $(grep -cE '\(cond |\(condp |\(case |\(when-not ' $F)"
echo "hx-swap-oob $(grep -c 'hx-swap-oob' $F)"
echo "mixed string hx- $(grep -cE '\"hx-[a-z]' $F)"
# route count: count this modal's entries in src/cljc/auto_ap/routes/*.cljc
```
## Results
Each migration appends one row (after-numbers), referencing the before in the diff.
| Phase | Modal | LOC | Routes | no-cursor twins | faked roots | snapshot merges | OOB | mixed hx- | cookbook reused / added |
|-------|-------|-----|--------|-----------------|-------------|-----------------|-----|-----------|-------------------------|
| 1 (baseline) | Transaction Edit `transaction/edit.clj` | 1608 | ~12 | 1 | 2 | ~75 | 0 | 8 | — / seeded 7 entries |
| 2 | Transaction Edit `transaction/edit.clj` | 1593 | **~5** | **0** | **0** | **0 round-trip** | 0 | 8 (shared) | location-select / **1 Selmer** |
| 2-final | Transaction Edit (full Selmer + wizard removed) | 1548 | **5** | 0 | 0 | 0 | 0 | **0** | full `sc/*` lib / **~30 partials** |
### New heuristics introduced at 2-final (full Selmer)
| # | Heuristic | Measure | Target |
|---|-----------|---------|--------|
| 9 | Hiccup HTML tags in the render path | `grep -cE '\[:(div\|span\|p\|a\|button\|input\|h[1-6]\|ul\|li\|label\|select\|option\|t(able\|head\|body\|r\|d\|h)\|form\|svg\|template)'` over the modal's render fns | → 0 (success-modal confirmation dialogs may keep the shared Hiccup component) |
| 10 | mm wizard coupling | `grep -c 'mm/' the modal file` + `grep -c 'defrecord.*Wizard\|ModalWizardStep'` | → 0 for a single-step modal |
> **Phase 2 progress.** Achieved with parity held (swap spec **6/6**, transaction-edit
> spec **8/8**, full suite **38 pass / 1 unrelated fail / 0 skip**, up from 30/2/7):
> - deleted the dead `*-no-cursor*` twin (no-cursor 1→0);
> - **de-faked the simple-mode cursor** (faked roots 2→0) via explicit data + explicit
> field names (`account-field-name`) + explicit error lookup — the render-fn rewrite the
> `with-field-default` shortcut couldn't do;
> - **collapsed the 5 manual-coding operation routes into one `edit-form-changed`
> dispatcher** (routes ~12→~5; the operations are now pure `apply-*` fns);
> - fixed a real production bug (`:mode` → 500 on every advanced manual save);
> - greened `transaction-edit.spec.ts` (8/8) and matured the skill.
>
> **Phase 2 complete.** The wizard→plain-form rewrite removed the snapshot round-trip
> (heuristic 2 → 0) and the first interactive component (`location-select`) is migrated to
> a Selmer template (`selmer-conventions.md` validated). Remaining for *later phases*: drop
> the now-thin `mm/ModalWizardStep` protocol wrappers, and the cross-cutting Phase 11
> Selmer sweep of the shared `com/typeahead`/`com/select`/`com/button-group-button` (those
> shared call sites hold the last 8 mixed `@`/`:`-attr offenders; they clear when the
> shared components move to Selmer — not a single-modal task, per Open decision 2).
> **Phase 2-final — full Selmer + wizard removed.** Every component the modal renders
> through was ported to a Selmer partial under `resources/templates/components/` with a
> thin Clojure wrapper in `auto-ap.ssr.components.selmer` (`sc/*`); the modal's own
> structure lives under `resources/templates/transaction-edit/`. The `mm` wizard
> abstraction (`EditWizard`/`LinksStep` records, `MultiStepFormState`, `step-params[...]`
> field names, `wrap-wizard`/`wrap-decode-multi-form-state` middleware) was deleted — there
> was only ever one step, so it was pure overhead. Result: heuristic 8 (mixed hx-) and 9
> (Hiccup in render) and 10 (mm coupling) all → **0**; the `edit-wizard-navigate` route is
> gone (routes 5). Parity held: swap spec **6/6**, transaction-edit spec **8/8**, full
> suite **38 pass / 1 pre-existing unrelated fail** (serial, fresh seed). The only Hiccup
> left in the file is the post-save `com/success-modal` confirmation dialogs (terminal,
> shared component — out of the form's render path). See `form-vs-wizard.md` (drop-the-
> wizard test), `selmer-conventions.md` (composition mechanics), and `gotchas.md`
> (stray-field decode leak; jetty reload staleness).

148
.claude/skills/ssr-form-migration/reference/selmer-conventions.md Normal file
View File

@@ -0,0 +1,148 @@
# Selmer template conventions
> **Validated** in the Transaction Edit migration: `location-select*` now renders from
> `resources/templates/components/location-select.html` via the interop bridge, embedded
> back into the Hiccup account row. Verified: swap spec 6/6, transaction-edit 8/8 (the
> Shared Location test selects through the Selmer `<select>`, saves, and spreads to DT).
## Why Selmer for interactive components
In Hiccup the same Alpine/HTMX attribute is sometimes a keyword and sometimes a string in
the same file — there's no rule a reader (or an LLM) can rely on. The real
`com/typeahead-` mixes them in one map:
```clojure
:x-modelable "value.value" ; keyword key
"x-ref" "hidden" ; string key
"@keydown.down.prevent.stop" "tippy?.show();" ; handlers MUST be strings
:x-init "..." ; structural attrs are keywords
```
In a Selmer template the same markup is unambiguous plain HTML:
```html
{# templates/components/typeahead.html #}
<div class="relative" x-data="{{ x_data|safe }}" x-model="{{ x_model }}">
<a class="{{ classes }}" x-ref="input" tabindex="0"
@keydown.down.prevent.stop="tippy?.show()"
@keydown.backspace="tippy?.hide(); value = {value:'', label:''}">
<span x-text="value.label"></span>
</a>
</div>
```
Note the `tippy?.` null-guard carried over from the swap doctrine — Selmer doesn't change
the Alpine-survives-swap requirement.
## The render helper + interop bridge (`auto-ap.ssr.selmer`)
```clojure
(sel/render template ctx) ; selmer/render-file -> HTML string (classpath-relative path)
(sel/render-str template ctx) ; render from a string (tests/REPL)
(sel/hiccup->html h) ; Hiccup -> string, for {{ frag|safe }} inside a template
(sel/raw html-string) ; wrap a rendered string so hiccup2 emits it verbatim
(sel/render->hiccup template ctx); render + raw, ready to drop into a Hiccup tree
```
The bridge works **both ways** (proven in `selmer_test`): a Hiccup component renders inside
a Selmer template (`hiccup->html` + `|safe`), and a Selmer fragment renders inside a Hiccup
tree (`render->hiccup`, which `raw`-wraps so hiccup2 doesn't double-escape).
## The worked example — `location-select*`
Template (`resources/templates/components/location-select.html`): plain HTML, an
`{% for %}` over option maps, `{% if opt.selected %}`.
```clojure
;; Clojure side: build the data, compute classes (reuse inputs/default-input-classes so
;; styling can't drift), render, and return a Hiccup-embeddable fragment.
(defn location-select* [{:keys [name client-locations value ...]}]
(let [options (cond ...) ; [[value label] ...]
selected (or value (ffirst options))
classes (str/join " " (conj (vec inputs/default-input-classes) "w-full"))]
(sel/render->hiccup "templates/components/location-select.html"
{:name name :classes classes
:options (for [[v l] options] {:value v :label l :selected (= v selected)})})))
```
Lessons:
- **Pass computed values in, don't hard-code.** Reuse the Clojure source of truth
(`inputs/default-input-classes`) as a context value rather than copying class strings
into the template — otherwise styling drifts from the shared components.
- **Verify by string-match + e2e, not byte-parity.** `hh/add-class` is set-based, so class
*order* differs from the old `com/select` output; CSS is order-independent and the e2e
proves behavior. (`testing-conventions`: don't assert on exact markup.)
- **Embed via the bridge.** `render->hiccup` lets the Selmer fragment sit inside the
still-Hiccup row (`com/validated-field` wraps it) — strangler, one component at a time.
## Composition — verified mechanics (selmer 1.12.61)
Proven by REPL before the full migration (do the same before relying on any of these):
- **`{% include %}` works in FILE renders only.** `sel/render` = `selmer/render-file`, and
include/extends/block are *parse-stage* tags. Rendering a template **string** that
contains `{% include %}` throws `unrecognized tag: :include` (the runtime expr-tag has a
nil handler). So includes only work from a `.html` file, never from `render-str`.
- **`{% include %}` sees `{% for %}` loop bindings.** Inside `{% for row in rows %}…{% include "components/x.html" %}…{% endfor %}` the partial can read `row.*`. Good for repeated
rows — though Clojure-composing the rows (below) is usually simpler.
- **`{% include … with k=v %}` is IGNORED** in 1.12.61 (the `with` clause is dropped). To
parametrize, either wrap with the block tag `{% with k=v %}{% include … %}{% endwith %}`
(works), or — preferred — let a Clojure wrapper render the partial with an explicit ctx.
## The Clojure-wrapper composition pattern (`auto-ap.ssr.components.selmer` / `sc`)
Because `{% include with %}` can't pass args and the server computes most values anyway,
each shared component is a **thin Clojure wrapper that renders its own partial** (the
proven `location-select*` shape, generalised). The element *structure* lives 100% in the
`.html`; the only Clojure is data assembly. The modal's render fns compose these wrappers
and assemble a view-model, interpolating the pre-rendered fragments as `{{ frag|safe }}`.
```clojure
(sc/hidden {:name … :value …}) ; -> render "components/hidden.html"
(sc/validated-field {:label … :errors …} body…)
(sc/typeahead {:name … :url … :value … :content-fn …}) ; resolves label server-side
(sc/data-grid {:headers […] :footer-tbody …} rows…)
```
### `attrs->str` — the dynamic-attribute bridge
HTMX/Alpine attributes vary per call site, so a fixed template can't enumerate them.
`sc/attrs->str` serialises an attribute *map* to an HTML attribute *string* injected with
`{{ attrs|safe }}`: `<input type="hidden"{{ attrs|safe }}>`. Rules mirror hiccup2 — nil/false
dropped, `true` → bare boolean attr, else `name="escaped"` (via `hu/escape-html`, so JSON
`x-data` and `x-init` quotes become `&quot;`/`&apos;` and the browser decodes them back).
Keyword keys keep their full name incl. namespaced/colon forms (`:x-hx-val:account-id` →
`x-hx-val:account-id`). This keeps templates free of per-attribute `{% if %}` ladders while
still emitting 100% Selmer markup — `attrs->str` serialises data, it does not build Hiccup.
### Reuse the real class helpers
Wrappers reuse `inputs/default-input-classes`, `inputs/use-size`, `hh/add-class`,
`btn/bg-colors` so output matches the Hiccup component **modulo Tailwind class order**.
Verify by class-**set** equality + e2e, never byte-parity (see the cookbook entries).
### Trivial wrapper divs
A bare `<div class="w-72">…</div>` around a fragment is composed with a `wrap-div` string
helper (or put the class in the parent template), not a Hiccup vector — string composition
of a structural wrapper is not Hiccup and avoids a micro-template per div.
Keep `|safe` to values the server fully controls (rendered fragments, JSON for `x-data`),
never raw user input.
## Scope (Open decision 2)
Hybrid, and the boundary is real: **the modal's attribute-heavy components delegate to the
shared `com/typeahead` / `com/select` / `com/button-group-button`.** Converting those is a
*cross-cutting* change (every modal uses them), so it belongs to the Phase 11 Selmer sweep,
not a single modal. `location-select*` is the first, self-contained proof; the shared
components follow when the sweep promotes them to Selmer partials.
## Attribute-consistency scorecard (heuristic 8)
```bash
grep -cE '"x-[a-z]|"hx-[a-z]|"@' <migrated-template> # → 0 mixed encodings in Selmer
```
A migrated Selmer template has no mixed `:x-`/`"x-"` encodings because everything is plain
HTML. (The Hiccup `"@click"`/`":class"` offenders that remain in `edit.clj` live in the
shared-component call sites — they clear when those components move to Selmer.)

149
.claude/skills/ssr-form-migration/reference/swap-doctrine.md Normal file
View File

@@ -0,0 +1,149 @@
# Whole-form HTMX swap doctrine
Every interactive control picks a swap strategy in this **priority order** (prefer the
earliest rule that works). Worked examples are the real `transaction/edit.clj` swaps.
## Rule 1 — No request when the field affects nothing else
Its value rides along in the form and is read on submit. No `hx-*` at all.
```clojure
;; transaction/edit.clj — the memo field. Editing it issues NO request; the value
;; just rides along until save. The e2e proves zero POSTs fire while typing.
(com/text-input {:value (fc/field-value)
:name (fc/field-name)
:id "edit-memo"
:placeholder "Optional note"})
```
## Rule 2 — Targeted swap of a single isolated cell when the effect is purely local
Give the cell a stable id, keep it **out of the typed input's subtree**, and post the
whole form but `hx-select` back only that cell.
```clojure
;; transaction/edit.clj — selecting an account only changes that row's valid Location
;; options, so the change swaps just this cell. Nothing else re-renders.
[:div {:id (str "account-location-" index)} ; stable, per-row id
(com/validated-field
{:x-hx-val:account-id "accountId"
:x-dispatch:changed "accountId" ; Alpine fires `changed` when account changes
:hx-trigger "changed"
:hx-post (bidi/path-for ssr-routes/only-routes ::route/edit-form-changed)
:hx-target (str "#account-location-" index)
:hx-select (str "#account-location-" index)
:hx-swap "outerHTML"
:hx-include "closest form"} ; whole form posts; only this cell swaps back
(location-select* {...}))]
```
## Rule 3 — Whole-form swap when the change touches interdependent state
Vendor change, add/remove row, mode toggle, $/% radio. The form's hidden state rides
along, so one swap keeps everything consistent — **no out-of-band swaps**.
```clojure
;; transaction/edit.clj — vendor change rebuilds the whole manual-coding section
;; (vendor default account, terms, etc. are interdependent).
[:div {:hx-trigger "change"
:hx-post (bidi/path-for ssr-routes/only-routes ::route/edit-vendor-changed)
:hx-target "#wizard-form"
:hx-select "#wizard-form"
:hx-swap "outerHTML"
:hx-sync "this:replace"
:hx-include "closest form"}
...]
```
The active tab/action round-trips through the form (it's a hidden field bound to Alpine
`activeForm`), so it **survives** the whole-form swap — that's why a whole-form swap is
safe here even though the user is "on" a tab.
## Rule 4 — OOB only for genuinely disjoint DOM regions
A global flash/toast, a nav badge, a modal at the document root. **If tempted to OOB
something inside the same feature, restructure instead**: give the dependent element a
common ancestor with the trigger and use an ordinary swap.
Worked example — running **totals live in their own sibling `<tbody>`** so an amount edit
swaps the totals without ever replacing the amount input:
```clojure
;; The totals tbody is a sibling of the input-bearing rows.
(com/data-grid
{:footer-tbody [:tbody {:id "account-totals"} ...totals rows...]}
...account rows with inputs...)
;; The amount input posts the whole form but hx-selects ONLY #account-totals.
(com/money-input
{:name (fc/field-name)
:id (str "account-amount-" index)
:class "w-16 account-amount-field"
:hx-post (bidi/path-for ssr-routes/only-routes ::route/edit-form-changed)
:hx-target "#account-totals" ; a SIBLING of this input's row...
:hx-select "#account-totals" ; ...so the input is never in the swapped region
:hx-swap "outerHTML"
:hx-trigger "keyup changed delay:300ms"
:hx-include "closest form"})
```
`grep -c hx-swap-oob` on a migrated modal must be `0` unless a justified disjoint-region
case is documented here and in `gotchas.md`.
---
## The focus invariant (must always hold)
> The input the user is typing in is never inside the region its own request swaps.
This is *the* reason the doctrine works. The amount field swaps a sibling tbody; the memo
field swaps nothing; the account typeahead's change swaps the whole form but the typeahead
isn't an active text caret at that moment (it's a click-to-select). The
`transaction-edit-swap.spec.ts` `sameNode` assertions exist to catch any violation.
## Alpine components must survive swaps
When a whole-form swap replaces a region containing Alpine/tippy components, they get
re-initialised from the server-provided values. Two hardening moves:
1. **Null-guard every reference** that depends on Alpine/tippy being initialised:
```clojure
"@keydown.down.prevent.stop" "tippy?.show()"
"@keydown.enter.prevent.stop" "$refs.input?.__x_tippy?.hide(); ..."
```
(`$refs.input?` / `tippy?` — the `?` matters; a swap can run a handler before re-init.)
2. **Let the server value win.** Because the section is rebuilt fresh on each swap, the
server-driven value (e.g. a vendor's default account) lands without keying tricks —
no preserved stale Alpine state to fight. The "changing the vendor a *second* time
still updates it" e2e is the regression guard for this.
If you *do* preserve a component across a morph/replace, key it by its server value so
a server-driven change forces re-init: `(assoc attrs :key (str id "--" current-value))`.
Use `hx/alpine-mount-then-appear` for rows that should mount-then-transition-in (it sets
`x-data {data-key false}`, `x-init $nextTick(() => key=true)`, `x-show key`).
---
## Selector strategy for targeted swaps (a consideration, not a mandate)
Rules 2 and 4 need a stable `hx-target`/`hx-select`. Per-element unique ids
(`#account-location-0`) work and are what transaction-edit uses today. They get noisy in
deeply repeated/nested structures. When you hit that (Phase 5 / the wizards), consider:
- **Semantic markup + data-attributes** — mark rows/cells with their identity and target
by attribute, no per-element ids:
```html
<tr data-row="account" data-index="0">
<td data-cell="location"> … </td>
</tr>
<!-- hx-target="[data-row='account'][data-index='0'] [data-cell='location']" -->
```
- **A `form-path -> selector` function**, derived the same way a cursor path is, so the
server and the markup agree on the target by construction. A render fn at form-path
`[:accounts 0 :location]` computes its own stable selector from that path.
**Decision status:** still per-element ids. The first modal to hit nested repeated swaps
(Invoice Bulk Edit, Phase 5) settles the convention and records it here + in
`component-cookbook.md` for the wizards to reuse.

137
.claude/skills/ssr-form-migration/reference/test-recipes.md Normal file
View File

@@ -0,0 +1,137 @@
# Test recipes
GROWS every migration. How to characterize and verify a modal. Consistent with the
project `testing-conventions` skill: test user-observable behavior, assert DB state
directly, don't test the means.
## The three test layers
1. **Characterization e2e first (Playwright).** Before changing a modal, write/confirm a
spec capturing *current* behavior — focus/caret survival across swaps, each field
round-trip, validation errors, the real save. This is the parity contract; keep it
green through every commit.
2. **Pure-function checks via REPL.** Once render/data-prep fns are pure, exercise them
with `clojure-eval` / `clj-nrepl-eval -p <port>`. Assert on returned data; for markup
use string matches (`(re-find #"accounts\[0\]\[account\]" (str html))`) — this style
survives the Selmer switch. Avoid brittle structural assertions.
3. **DB-state assertions for mutations.** If a submit writes Datomic, verify by querying
the DB, not by asserting on markup.
## Running e2e
```bash
npx playwright test # full suite
npx playwright test e2e/transaction-edit-swap.spec.ts # one spec
```
- Config: `playwright.config.ts`, `baseURL http://localhost:3333`, `webServer:
lein run -m auto-ap.test-server`, `reuseExistingServer: !CI`.
- **The server must be from the worktree you're testing.** `reuseExistingServer` will
silently reuse *any* server on `:3333` — including another worktree's. Confirm with
`ls -la /proc/$(lsof -ti :3333)/cwd` (or restart on a clean port) before trusting a run.
- The test-server port is hardcoded (`test_server.clj` `run-jetty {:port 3333}`); to run a
second server from another worktree, change that or parameterise it.
## Driving a typeahead in e2e (Solr unavailable in tests)
```js
await typeahead.locator('a[x-ref="input"]').click(); // open tippy dropdown
const search = page.locator('[data-tippy-root] input[x-model="search"]').first();
await search.fill('te'); // under 3-char Solr threshold
await typeahead.evaluate((el, id) => { // inject a clickable result
window.Alpine.$data(el).elements = [{ value: id, label: 'Test Account' }];
}, accountId);
await page.locator('[data-tippy-root] a', { hasText: 'Test Account' }).first().click();
```
Entity ids come from `GET /test-info` (`{accounts:{test-account, vendor, vendor2, ...}}`).
## Proving the focus invariant (caret survival) — the key swap test
```js
// before the debounced swap lands, capture the live focused node...
await page.evaluate(() => { window.__focused = document.activeElement; });
await swap; // waitForResponse on the *-form-changed POST
const ok = await page.evaluate(() => {
const a = document.activeElement;
return { sameNode: a === window.__focused, value: a?.value, caret: a?.selectionStart };
});
// ...assert the SAME node survived with value + caret intact.
```
`trackErrors(page)` (collect `pageerror` + `console.error`, assert `[]`) catches a swap
that throws on a stale `$refs`/`tippy` — pair it with every swap test.
## Asserting "no request" (Rule 1 fields)
```js
let posts = 0;
page.on('request', r => { if (r.url().includes('edit-form-changed') && r.method()==='POST') posts++; });
// ...type in the memo...
expect(posts).toBe(0); // memo affects nothing → issues no request
```
---
## E2E baseline (the regression gate — never drop below this)
The full suite must stay green after every migration. Specs touching the migrated modals:
| Spec | Tests | Role |
|------|-------|------|
| `e2e/transaction-edit-swap.spec.ts` | 8 | **Phase 2 parity contract** — whole-form `hx-select` swaps, caret survival, no-request memo, vendor re-select |
| `e2e/transaction-edit.spec.ts` | 15 | transaction edit behavior |
| `e2e/bulk-code-transactions.spec.ts` | 18 | Phase 3 (bulk code) |
| `e2e/transaction-import.spec.ts` | 4 | import |
| `e2e/transaction-navigation.spec.ts` | 13 | navigation |
### Running e2e from a non-default worktree (recipe)
`:3333` is often taken by another worktree's server. To run this worktree's code:
1. Boot the test server in-process on this worktree's REPL at an alternate port — no
second JVM, and it live-reloads as you edit:
```clojure
(require '[auto-ap.test-server :as ts] '[ring.adapter.jetty :refer [run-jetty]]
'[datomic.api :as dc])
;; reseed helper — call before each full run so state doesn't leak between runs
(defn reseed! []
(try (.stop (:server test-srv)) (catch Throwable _))
(try (dc/delete-database "datomic:mem://playwright-test") (catch Throwable _))
(def test-srv (let [c (ts/create-test-db) id (ts/seed-test-data c)]
(reset! ts/test-transaction-id id)
{:server (run-jetty (ts/test-app) {:port 3334 :join? false}) :tx-id id})))
(reseed!)
```
2. `playwright.config.ts` honors `BASE_URL`; setting it also disables the auto-started
webServer (so worktrees don't fight over :3333):
```bash
BASE_URL=http://localhost:3334 npx playwright test --workers=1 --reporter=line
```
3. **Reseed (`reseed!`) before each full run.** One long-lived in-process server persists
its in-mem DB across separate `npx playwright` invocations; the swap spec's
`clearAccounts`/save mutate the shared transaction and leak into later specs. The
normal harness avoids this by booting a fresh server per `npx playwright test`.
### Pass/fail baseline — measured on the merged hx-select reference (Phase 2 start)
Server: in-process from `integreat-execute-refactor` on `:3334`, `--workers=1`, fresh seed.
| Spec | Result |
|------|--------|
| `transaction-edit-swap.spec.ts` | **6 / 6 pass** — the whole-form swap parity contract |
| `transaction-edit.spec.ts` | **1 fail (masks 7 via `mode: 'serial'`)** — `Shared Location … spread on save and reopen` fails: the save POST returns a validation error (amount/balance test-data assumption: "$200 = full amount of the 2nd transaction" doesn't hold), so the modal stays open. **Pre-existing on the merged reference, not introduced by this work.** |
| Full suite (39) | **30 pass / 2 fail / 7 skipped.** 2nd failure: `transaction-navigation.spec.ts` date-range persistence (`date-range=all` expected, got `month`) — drift from the base branch's "require Apply for date-range filters" change, unrelated to forms. |
**Gate for the Transaction Edit refactor:** the 6/6 swap-doctrine spec + REPL pure-fn
checks.
### Current state — after the Phase 2 modal work (never drop below this)
Full suite (workers=1, fresh seed): **38 passed / 1 failed / 0 skipped.**
- `transaction-edit-swap.spec.ts` — **6/6** (parity contract held through every change).
- `transaction-edit.spec.ts` — **8/8** (was 1 pass + 7 masked). Greened by: the `:mode`
500 fix, the Alpine-v3 typeahead helper, rewriting the percentage-split test to avoid
the snapshot-drops-live-values ordering trap, reading the real transaction total instead
of a hard-coded `400`, and dropping the removed `"Transaction Actions"` wizard-nav step.
- Remaining 1 failure: `transaction-navigation.spec.ts:92` date-range-preset persistence —
**unrelated to forms** (drift from the base branch's "require Apply for date-range
filters" change). Pre-existing; out of scope for this migration.