Search select

Copy this

<div class="search-select hm-measure" data-widget="search_select" data-blur-grace-ms="200" data-confirm-hold-ms="1800">
  <input type="hidden" name="company" id="hm-ss-field" value="">
  <input type="text" id="hm-ss-input" class="search-select-input" name="q" form="hm-detached-q" placeholder="Search companies, people, SKUs…" autocomplete="off" role="combobox" aria-expanded="false" aria-controls="hm-ss-results" aria-autocomplete="list" aria-haspopup="listbox" hx-get="/mock/typeahead" hx-trigger="keyup changed delay:300ms[this.value.trim().length>0]" hx-target="#hm-ss-results" hx-params="q">
  <div id="hm-ss-results" role="listbox" aria-label="Suggestions" class="search-select-results">
    <div class="search-select-prompt" role="option" aria-disabled="true">Type to search — rows share one anatomy; media is optional</div>
  </div>
</div>

Server exchange

When the client affordance finishes (click, confirm, keystroke…), htmx issues this request. Your API must return the response fragment in the table — usually HTML, not JSON (unless the partial says otherwise). Dazzle often renders these routes from the app model; a standalone HTMX4 app implements them explicitly. The Envelope column is the exchange envelope (part of the Swap contract) — what the response may re-emit relative to the persistent slot.

Do not reimplement the gallery. Flash toasts (e.g. “Deleted (demo).”), /mock/* paths, and other static-site scaffolding are demo-only (MOCK_HTMX in site/build_site.py). They are not Hyperpart surface and not a product API. If an agent is stuck “making the toast work,” stop — implement the exchange row below instead.

GET /app/fragments/search?source={source}&q= — example handler

HTMX4 / standalone HM: return HTML fragments. Dazzle often emits this for you from the model; agents building a plain FastAPI app should match this shape. Not a dual-lock module — application code. Not a gallery mock. Respect exchange envelope body_only on the response.

# Search exchange — map domain → fixed row anatomy.
# Do NOT invent a new picker per entity shape.
from fastapi import FastAPI, Query
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/app/fragments/search", response_class=HTMLResponse)
def search(source: str, q: str = Query("")) -> str:
    # rows = query_domain(source, q)
    # return "".join(render_result_row(SearchResultRow(
    #     id=r.id, name=r.title, secondary=r.meta,
    #     media_html=r.avatar_html or "",
    #     select_url=f"/app/fragments/select?source={source}&id={r.id}",
    #     results_target="#search-results-company",
    # )) for r in rows)
    return (
        '<div class="search-result-row" role="option" '
        'hx-get="/app/fragments/select?source=companies&id=1" '
        'hx-target="#search-results-company" hx-swap="innerHTML">'
        '<div class="search-result-body">'
        '<div class="search-result-name">Acme Ltd</div>'
        '<div class="search-result-secondary">Co. 123</div>'
        "</div></div>"
    )

GET /app/fragments/select?source={source}&id={id} — example handler

HTMX4 / standalone HM: return HTML fragments. Dazzle often emits this for you from the model; agents building a plain FastAPI app should match this shape. Not a dual-lock module — application code. Not a gallery mock. Respect exchange envelope body_only on the response.

# Select exchange — fill the hidden FK server-side.
from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/app/fragments/select", response_class=HTMLResponse)
def select(source: str, id: str) -> str:
    # label = load_label(source, id)
    return (
        f'<div class="select-result-confirm" role="status">'
        f"Selected {id}</div>"
        # + OOB: <input type=hidden name=… value=id hx-swap-oob>
        # + OOB: typeahead value=label hx-swap-oob
    )

Swap contract

Agent-visible HTMX topology (ADR-0054 / decision 0012). exchange envelope = what the response may re-emit relative to the persistent slot (body_only | outer | none | host_owned | document). dual-lock validates part markup only — not this envelope. Stem: stems/morph-safe-hypermedia.md; decision: docs/decisions/0012-swap-identity-contract.md.

Gallery mocks may approximate morph with innerHTML — production follows the Swap + Envelope columns in Server exchange.

Exchanges (swap · envelope)

• GET /app/fragments/search?source={source}&q= → innerHTML into the listbox · envelope=body_only
• GET /app/fragments/select?source={source}&id={id} → innerHTML (listbox) + OOB for hidden/input as needed · envelope=body_only

Envelope rules

• body_only — innerHTML / innerMorph into a slot; response is interior only (no re-wrap of slot id / nested data-dz-region).
• outer — outerHTML / outerMorph; response may carry identity.
• none — no HTML swap (JSON/204/bytes; client or OOB companion).
• host_owned — swap target/mode chosen by the host button’s hx-target / hx-swap.
• document — full navigation / document load (not a fragment).
• Slot owns stable id / domain keys; state in DOM, not Alpine.

Envelope response examples

What the server returns for each exchange on Search select. Match the exchange envelope; dual-lock still applies to interior markup.

GET /app/fragments/search?source={source}&q= · envelope=body_only

Correct response for body_only into .dz-search-results (innerHTML / innerMorph). Wrong: re-wrapping the slot.

Do — correct response body

<!-- envelope=body_only → results list rows / empty prompt -->
<div class="dz-search-result-row" role="option">
  <div class="dz-search-result-name">Acme Ltd</div>
  <div class="dz-search-result-secondary">Co. 123</div>
</div>

Don’t — violates body_only

<!-- WRONG: entire search field + listbox chrome -->
<div class="dz-search-box" data-dz-search-box id="slot">
  <input type="search" />
  <div>…results…</div>
</div>

GET /app/fragments/select?source={source}&id={id} · envelope=body_only

Correct response for body_only into .dz-search-results (innerHTML / innerMorph). Wrong: re-wrapping the slot.

Do — correct response body

<!-- envelope=body_only → results list rows / empty prompt -->
<div class="dz-search-result-row" role="option">
  <div class="dz-search-result-name">Acme Ltd</div>
  <div class="dz-search-result-secondary">Co. 123</div>
</div>

Don’t — violates body_only

<!-- WRONG: entire search field + listbox chrome -->
<div class="dz-search-box" data-dz-search-box id="slot">
  <input type="search" />
  <div>…results…</div>
</div>

How to use it

Seams

• shell: hidden FK + typeahead input + listbox panel (`data-widget=search_select`)
• data-blur-grace-ms (default 200) — blur→close delay so row clicks land; data-confirm-hold-ms (default 1500, alias confirm-dwell-ms) — auto-dismiss hold after .select-result-confirm paints
• search exchange returns N× fixed result-row fragments (or `.search-result-empty`) — map domain into name / secondary / optional media (omit media for text-only rows)
• each row carries its own hx-get to the select exchange
• select exchange: confirm line (+ OOB hidden FK / label) — never invent a selected id client-side; typing clears a stale FK
• hx-trigger debounce + min-length filter; controller restores the prompt on empty/whitespace (do not hx-get q=)
• name=q on the typeahead (form=hm-detached-q so leftover is not posted; form="" is invalid HTML, cycle 2140) so leftover query reaches the search exchange — mock must filter; leftover zzz must not invent Aurora (cycle 2138)

Do / Don't

Pitfalls

• empty / whitespace query must not hx-get a canned hit list
• leftover typed query must not invent the canned Aurora list (name=q + mock filter; same class as command leftover 2130)
• clear after a hit must restore the prompt — do not leave stale Aurora rows
• blur grace is NOT confirm hold — without confirm-hold-ms the select feedback is hidden as soon as focus leaves (~200ms)
• form posts the hidden input, never the visible text (typeahead input clears a stale FK; required uses setCustomValidity)
• do not invent a new combobox Hyperpart for 'users vs companies' — same row anatomy, different field mapping; missing media is valid
• media is optional free HTML inside `.search-result-media` (img, initials, icon) — keep primary text in `.search-result-name`

Keyboard / AT

• aria-expanded / data-open flip on focusin/focusout for the results panel
• result rows are role=option with their own activatable hx-get
• media slot is aria-hidden when decorative (initials/icon)

Related parts

field search-box avatar

DOM contract

What the emitted HTML must satisfy — the table is the required surface; Python under contracts/ is the package-internal dual-lock CI runs (tests/test_contracts.py), not an app route. Standalone HTMX4: implement the API so responses match this markup. Dazzle: the agent emits SSR that already satisfies it. Do not invent attrs outside these tables. For request/response wiring see Server exchange.

contracts/search_select.py

Required in the DOM: root [data-widget="search_select"] (part search-select). Emit only these attributes — inventing extras is fine only if controllers ignore them; omitting required ones fails CI (tests/test_contracts.py).

Ingestion model SearchResultRow

Server-side shape before render — one normalisation boundary for producers.

Exemplar render()

Executable in CI: the Python below is render(); the boxed preview is render(EXEMPLARS[0]) — the first fixture the dual-lock tests emit, not a separate widget and not gallery mock data.

def render(row: SearchResultRow) -> str:
    return render_result_row(row)

Notes

Source files

One logical Hyperpart, 4 code items (CSS layered, JS bundled). Bound by HYPERPART: search-select — python tools/hyperpart.py search-select lists them.

site/registry.py · contracts/search_select.py · components/search-select.css:1 · controllers/dz-search-select.js