refactor(ssr): full Selmer migration of Transaction Edit; remove the wizard
Migrate every part of the Transaction Edit modal's HTML to Selmer templates
(zero Hiccup in the render path) and delete the mm multi-modal "wizard"
abstraction entirely -- there was only ever one step.
- New auto-ap.ssr.components.selmer (sc) + ~22 shared component partials under
resources/templates/components/ (typeahead, button-group, radio-card,
data-grid, validated-field, modal, buttons, inputs, SVGs). Each wrapper renders
its own partial; dynamic HTMX/Alpine attrs bridge via attrs->str -> {{attrs|safe}}.
- 15 modal templates under resources/templates/transaction-edit/.
- Delete EditWizard/LinksStep records + all mm/* usage. Plain handlers: flat
wrap-decode-edit (fields renamed off step-params[...], stray keys stripped),
flat wrap-derive-state, *errors*-based field errors, generic wrap-form-4xx-2.
- Drop the edit-wizard-navigate route (routes ~12 -> 5).
- Fix: stray `method` (tab button-group hidden) leaked into the upsert -> 500;
strip decoded map to schema keys.
- e2e selectors updated (#wizard-form->#edit-form, #wizardmodal->#editmodal,
step-params[...] field names). Parity: swap 6/6, edit 8/8, suite 38/1
(1 pre-existing unrelated nav test).
- ssr-form-migration skill updated with the learnings (composition mechanics,
sc/* library, drop-the-wizard recipe, scorecard row, 3 new gotchas).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -149,3 +149,34 @@ divergence). Scorecard heuristic 1: faked roots → 0.
|
||||
```
|
||||
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).
|
||||
|
||||
@@ -13,9 +13,13 @@ implement the multi-step protocol (`mm/ModalWizardStep` + friends), serialize an
|
||||
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
|
||||
|
||||
`transaction/edit.clj` today still carries the old shape, useful as the "before":
|
||||
The old shape (kept here as the "before"):
|
||||
|
||||
```clojure
|
||||
(defrecord LinksStep [linear-wizard]
|
||||
@@ -49,6 +53,33 @@ A `?mode=` toggle is just the `GET` re-rendering with a different query param
|
||||
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
|
||||
|
||||
@@ -148,6 +148,52 @@ hides every test after the first failure, so fixing one unmasks the next):
|
||||
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. Clean signal: restart (re-seed) + **`--workers=1`**.
|
||||
Baseline is **38 pass / 1 fail**, the 1 being the pre-existing
|
||||
`transaction-navigation.spec.ts:92` date-range test (unrelated to the edit modal).
|
||||
|
||||
## Scorecard exceptions (ratchet violations with a reason)
|
||||
|
||||
_None yet._ Append here if a migration must let a metric regress for a documented 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.
|
||||
|
||||
@@ -40,6 +40,14 @@ Each migration appends one row (after-numbers), referencing the before in the di
|
||||
|-------|-------|-----|--------|-----------------|-------------|-----------------|-----|-----------|-------------------------|
|
||||
| 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):
|
||||
@@ -59,3 +67,18 @@ Each migration appends one row (after-numbers), referencing the before in the di
|
||||
> 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).
|
||||
|
||||
@@ -75,11 +75,60 @@ Lessons:
|
||||
- **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
|
||||
## Composition — verified mechanics (selmer 1.12.61)
|
||||
|
||||
Selmer composes via `{% include %}` and `{% block %}`. Prefer small per-component templates
|
||||
referenced by classpath path. Keep `|safe` to values the server fully controls (rendered
|
||||
Hiccup, JSON for `x-data`), never raw user input.
|
||||
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 `"`/`'` 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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user