# 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

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.

## 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.)