.. _library_http_htmx:

``http_htmx``
=============

The ``http_htmx`` library provides router-agnostic helpers for HTMX
request classification, HTML reply construction, and HTMX
response-header decoration using normalized ``http_core`` request and
response terms.

Currently this library provides:

- HTMX request detection helpers
- ``reply/3-4`` helpers for pre-rendered HTML atoms and ``html``
  terms/lists
- ``page_fragment_reply/4-5`` helpers for full-page replies on ordinary,
  boosted, and history-restore HTMX requests and fragment replies on
  other HTMX requests
- ``add_response_headers/4`` for the common ``HX-*`` response headers
- the companion ``http_router_htmx`` category for router middleware
  integration

API documentation
-----------------

Open the
`../../apis/library_index.html#http_htmx <../../apis/library_index.html#http_htmx>`__
link in a web browser.

Loading
-------

To load the library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(http_htmx(loader)).

Testing
-------

To test this library, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(http_htmx(tester)).

Current scope
-------------

The current library provides one public object and one companion
category:

- object ``http_htmx``
- category ``http_router_htmx``

The main public predicates are:

- ``is_htmx_request/1``
- ``is_boosted_request/1``
- ``is_history_restore_request/1``
- ``is_fragment_request/1``
- ``request_kind/2``
- ``current_url/2``
- ``current_url_abs_path/2``
- ``prompt/2``
- ``target/2``
- ``trigger/2``
- ``trigger_name/2``
- ``request_property/2``
- ``request_properties/2``
- ``reply/3``
- ``reply/4``
- ``page_fragment_reply/4``
- ``page_fragment_reply/5``
- ``add_response_headers/4``

The companion router category provides these middleware handler
predicates:

- ``annotate_htmx_request/2``
- ``add_htmx_response_headers/3``

For handlers that only need one HTMX request flag or value, prefer
``request_property/2``. Use ``request_properties/2`` when you need the
full derived property list, for example when annotating a request with
all HTMX metadata. The derived property set now also includes
``htmx_request_kind(Kind)``, mirroring ``request_kind/2`` for middleware
and other property-oriented consumers.

For handlers that need the same full-page versus fragment decision used
by ``page_fragment_reply/4-5``, prefer ``is_fragment_request/1`` instead
of repeating the ``HX-Request``, ``HX-Boosted``, and
``HX-History-Restore-Request`` checks.

For handlers that need one mutually exclusive classification for control
flow or presentation, prefer ``request_kind/2`` instead of open-coding
precedence between ordinary, fragment, boosted, and history-restore
requests.

For handlers that need a same-origin absolute-path form of
``HX-Current-URL``, prefer ``current_url_abs_path/2``. It returns the
path plus optional query and fails when the current URL does not match
the request scheme and host information.

The supported response-header options are currently:

- ``redirect(URL)``
- ``refresh(Boolean)``
- ``vary_hx_request(Boolean)``
- ``location(Value)``
- ``push_url(Value)``
- ``replace_url(Value)``
- ``reswap(Value)``
- ``retarget(Value)``
- ``reselect(Value)``
- ``trigger(Value)``
- ``trigger_after_settle(Value)``
- ``trigger_after_swap(Value)``

HTMX response headers are only added for non-``3xx`` responses. When a
request is an HTMX request and the selected options would emit one or
more ``HX-*`` response headers, attempting to combine those options with
a ``3xx`` response status raises an error instead of silently generating
headers that HTMX will ignore. If you need a normal HTTP redirect, use
the standard response headers directly.

When an endpoint can return both a full-page reply and an HTMX fragment
for the same URL, set ``vary_hx_request(true)`` so the helpers merge
``Vary: HX-Request`` with any existing ``Vary`` metadata. Otherwise,
browser or intermediary caches can reuse the wrong representation.

History restore requests after an HTMX history-cache miss are expected
to return the full page. The ``page_fragment_reply/4-5`` helpers
therefore treat ``HX-History-Restore-Request`` the same as ordinary or
boosted navigation. If your application uses ``HX-Request`` to select
between page and fragment representations, configure the client with
``htmx.config.historyRestoreAsHxRequest`` set to ``false`` so that
history restores do not also carry ``HX-Request``.

Structured values for ``location/1`` and the trigger options reuse the
repository JSON-term conventions through the shared HTTP JSON helpers,
with HTMX-specific validation of the top-level shape:

- ``location/1`` accepts either a URL atom or a JSON object with a
  required ``path`` key and only the documented HTMX optional keys
  (``source``, ``event``, ``handler``, ``target``, ``swap``, ``values``,
  ``headers``, ``select``, ``selectOOB``, ``push``, and ``replace``)
- ``trigger/1``, ``trigger_after_settle/1``, and
  ``trigger_after_swap/1`` accept either a single event atom, a list of
  event atoms, or a JSON object whose top-level keys are event names

The router companion category expects HTMX response options to be
provided as ``htmx_response_options(Options)`` request metadata or
response properties.
