wtforms-htmx 0.1.0__py3-none-any.whl

wtforms_htmx/mutations.py

@@ -0,0 +1,311 @@
+"""Built-in callbacks for trigger declarations.
+
+Each callback takes ``(form, source, target)``. ``value_set``,
+``value_cycle`` and ``list_move`` build such a callback. The ones for a
+SelectMultipleField or a FieldList raise TypeError on another target type.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from wtforms.fields import FieldList
+from wtforms.fields import SelectMultipleField
+
+from .triggers import TriggerCallback
+
+
+def _entry_is_padding(entry: Any) -> bool:
+    """Whether ``entry`` comes from ``min_entries`` padding rather than formdata.
+
+    A padded field has ``raw_data == []``. FormField and FieldList entries
+    are checked through their sub-fields.
+    """
+    if hasattr(entry, "form"):
+        return all(_entry_is_padding(f) for f in entry.form._fields.values())
+
+    if hasattr(entry, "entries"):
+        return all(_entry_is_padding(e) for e in entry.entries)
+
+    return entry.raw_data == []
+
+
+def _truncate_to_padding(field: FieldList) -> None:
+    """Drop the trailing entries that come from ``min_entries`` padding.
+
+    Mutations then only see the entries the user submitted.
+    """
+    while field.entries and _entry_is_padding(field.entries[-1]):
+        field.pop_entry()
+
+
+def _require(target: Any, field_class: type, name: str) -> None:
+    """Raise TypeError when ``target`` is not a ``field_class``."""
+    if not isinstance(target, field_class):
+        raise TypeError(
+            f"{name} requires {field_class.__name__}, got {type(target).__name__}"
+        )
+
+
+def _source_value(source: Any) -> str:
+    """Return the source's value: ``raw_data[0]`` stripped, or ``""``."""
+    raw = getattr(source, "raw_data", None)
+    return raw[0].strip() if raw else ""
+
+
+def _source_index(source: Any) -> int | None:
+    """Return the source's value as an integer, or ``None`` when it is not one."""
+    try:
+        return int(_source_value(source))
+    except ValueError:
+        return None
+
+
+def value_set(value: Any) -> TriggerCallback:
+    """Return a mutation that overwrites ``target.data`` with ``value``.
+
+    Use it to clear a field (``value_set("")`` / ``value_set(None)``) or
+    to reset it to a default, for example from a "clear" button::
+
+        query = StringField()
+        clear = ButtonField("Clear").triggers("query", value_set(""))
+    """
+
+    def _mutation(form: Any, source: Any, target: Any) -> None:
+        target.data = value
+
+    return _mutation
+
+
+def value_cycle(values: list[Any]) -> TriggerCallback:
+    """Return a mutation that rotates ``target.data`` through ``values``.
+
+    Each firing advances ``target.data`` to the next entry, wrapping around
+    at the end. If the current ``target.data`` isn't in ``values`` (for
+    example, when the field is empty), the mutation resets to ``values[0]``.
+
+    Use it with a single :class:`~wtforms.fields.ButtonField` for status
+    toggles, view/edit modes or step indicators. No value is read from
+    the source. Raise :exc:`ValueError` when ``values`` is empty.
+
+    Cycle a status field from one button::
+
+        STATES = ["todo", "doing", "done"]
+        status = SelectField(choices=STATES)
+        cycle = ButtonField("·").triggers("status", value_cycle(STATES))
+    """
+    if not values:
+        raise ValueError("value_cycle() needs at least one value")
+
+    def _mutation(form: Any, _source: Any, target: Any) -> None:
+        current = target.data or ""
+        if current not in values:
+            target.data = values[0]
+            return
+
+        target.data = values[(values.index(current) + 1) % len(values)]
+
+    return _mutation
+
+
+def value_add(form: Any, source: Any, target: Any) -> None:
+    """Append the source's value to a :class:`~wtforms.fields.SelectMultipleField`'s data.
+
+    No deduplication: clicking a button whose value is already in
+    ``target.data`` adds a duplicate entry. Filter at the source if
+    uniqueness matters (e.g. exclude already-selected values from the
+    candidate set).
+
+    Each catalog button carries its option's value::
+
+        tags = SelectMultipleField(choices=CATALOG)
+        add_tag = ButtonField("Add").triggers("tags", value_add)
+
+    Render one button per option and pass the value at render time:
+
+    .. code-block:: jinja
+
+        {% for value, label in form.tags.choices %}
+          {{ form.add_tag(value=value, label=label, id=False) }}
+        {% endfor %}
+    """
+    _require(target, SelectMultipleField, "value_add")
+
+    value = _source_value(source)
+    if not value:
+        return
+
+    target.data = [*list(target.data or []), value]
+
+
+def value_remove(form: Any, source: Any, target: Any) -> None:
+    """Remove the first occurrence of the source's value from a :class:`~wtforms.fields.SelectMultipleField`'s data.
+
+    Subsequent matches (if duplicates exist) are left untouched,
+    like :meth:`list.remove`.
+
+    Each chip "×" button carries its value::
+
+        tags = SelectMultipleField(choices=CATALOG)
+        rm_tag = ButtonField("×").triggers("tags", value_remove)
+
+    .. code-block:: jinja
+
+        {% for value in form.tags.data or [] %}
+          {{ value }} {{ form.rm_tag(value=value, id=False) }}
+        {% endfor %}
+    """
+    _require(target, SelectMultipleField, "value_remove")
+
+    value = _source_value(source)
+    data = list(target.data or [])
+    if value in data:
+        data.remove(value)
+
+    target.data = data
+
+
+def list_add(form: Any, source: Any, target: Any) -> None:
+    """Append or insert an entry into a :class:`~wtforms.fields.FieldList`.
+
+    The insertion position is read from the source's value (typically
+    the clicked button's ``value=``). An empty string appends a fresh
+    entry at the end of the list. An integer inserts at that absolute
+    index and shifts the following entries one slot to the right. Any
+    other value does nothing.
+
+    Append a row from an Add button::
+
+        tasks = FieldList(StringField())
+        add_task = ButtonField("+ Add task").triggers("tasks", list_add)
+    """
+    _require(target, FieldList, "list_add")
+
+    _truncate_to_padding(target)
+    if not _source_value(source):
+        target.append_entry()
+        return
+
+    index = _source_index(source)
+    if index is not None:
+        target.insert_entry(index)
+
+
+def list_remove(form: Any, source: Any, target: Any) -> None:
+    """Remove an entry from a :class:`~wtforms.fields.FieldList`.
+
+    The position is read from the source's value: an empty string
+    pops the last entry, while an integer drops the entry at that
+    absolute index. Any other value does nothing. Remaining entries are
+    re-indexed contiguously. An index captured client-side before the
+    call is then stale.
+
+    Remove a row from a per-row × button::
+
+        tasks = FieldList(StringField())
+        rm_task = ButtonField("×").triggers("tasks", list_remove)
+    """
+    _require(target, FieldList, "list_remove")
+
+    _truncate_to_padding(target)
+    index = _source_index(source) if _source_value(source) else len(target) - 1
+    if index is not None and 0 <= index < len(target):
+        target.pop_entry(index)
+
+
+def list_clear(form: Any, _source: Any, target: Any) -> None:
+    """Empty a :class:`~wtforms.fields.FieldList` of all its entries.
+
+    Entries added afterwards in the same request are numbered from
+    ``0``.
+
+    Empty the whole list from one button::
+
+        tasks = FieldList(StringField())
+        clear = ButtonField("Clear all").triggers("tasks", list_clear)
+    """
+    _require(target, FieldList, "list_clear")
+
+    target.entries = []
+    target.last_index = -1
+
+
+def list_reorder(form: Any, source: Any, target: Any) -> None:
+    """Reorder a :class:`~wtforms.fields.FieldList` in the order given by the source's value.
+
+    The value is a comma-separated list of the *old* indices in their
+    new order, e.g. ``"0,2,1"`` rebuilds the list as
+    ``[old[0], old[2], old[1]]``. The indices must cover
+    ``range(len(target))`` exactly once. A partial, duplicate or
+    out-of-range permutation does nothing, so a stale client request
+    cannot silently truncate or duplicate entries.
+
+    A hidden field carries the new index order (written client-side)::
+
+        tasks = FieldList(StringField())
+        reorder = HiddenField().triggers("tasks", list_reorder, on="change")
+    """
+    _require(target, FieldList, "list_reorder")
+
+    _truncate_to_padding(target)
+    value = _source_value(source)
+    if not value:
+        return
+
+    try:
+        order = [int(part) for part in value.split(",")]
+    except ValueError:
+        return
+
+    if sorted(order) != list(range(len(target.entries))):
+        return
+
+    _rebuild_in_order(target, order)
+
+
+def list_move(offset: int) -> TriggerCallback:
+    """Return a mutation that moves a :class:`~wtforms.fields.FieldList` entry by ``offset``.
+
+    The entry index is read from the source's value. ``-1`` moves the
+    entry one row up, ``+1`` one row down. A move past either end of
+    the list, a missing value or a value that is not an index does
+    nothing. Remaining entries are re-indexed contiguously.
+
+    Move a row from per-row ↑ / ↓ buttons, an alternative to dragging
+    that works without JavaScript::
+
+        tasks = FieldList(StringField())
+        move_up = ButtonField("↑").triggers("tasks", list_move(-1))
+        move_down = ButtonField("↓").triggers("tasks", list_move(+1))
+    """
+
+    def _mutation(form: Any, source: Any, target: Any) -> None:
+        _require(target, FieldList, "list_move")
+
+        _truncate_to_padding(target)
+        idx = _source_index(source)
+        if idx is None:
+            return
+
+        new = idx + offset
+        n = len(target.entries)
+        if not (0 <= idx < n and 0 <= new < n):
+            return
+
+        order = list(range(n))
+        order.insert(new, order.pop(idx))
+        _rebuild_in_order(target, order)
+
+    return _mutation
+
+
+def _rebuild_in_order(target: FieldList, order: list[int]) -> None:
+    """Rebuild ``target`` with its entries taken in ``order`` (old indices)."""
+    # Snapshot data in the desired order before draining: pop_entry
+    # mutates entries in place and reindexes after each call.
+    data_in_order = [target.entries[i].data for i in order]
+    for _ in range(len(order)):
+        target.pop_entry()
+
+    for data in data_in_order:
+        target.append_entry(data)

wtforms_htmx/partial.py

@@ -0,0 +1,308 @@
+"""Build the partial response of a form, as an ``HtmxResponse``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import copy
+from dataclasses import dataclass
+from dataclasses import field
+from html.parser import HTMLParser
+from typing import Any
+from typing import TYPE_CHECKING
+
+from markupsafe import Markup
+from wtforms.fields import Field
+
+from .headers import _HtmxRequestInfo
+from .headers import _parse_request
+
+if TYPE_CHECKING:
+    from .form import HtmxFormMixin
+
+
+@dataclass(frozen=True, slots=True)
+class HtmxResponse:
+    """An htmx partial response.
+
+    Pairs the body to return with any htmx response headers the
+    library computed for it.
+    """
+
+    body: str
+    """The rendered HTML fragment to send back to the client."""
+
+    headers: Mapping[str, str] = field(default_factory=dict)
+    """htmx response headers the library computed for this response.
+
+    The library sets :htmx-header:`hx-retarget` (when the fragment's
+    outer element is not the element htmx targeted) and
+    :htmx-header:`hx-reswap` (``none`` when a selector target's callback
+    returns no body). Add any other htmx response header yourself
+    (:htmx-header:`hx-trigger` to fire a client event,
+    :htmx-header:`hx-redirect`, :htmx-header:`hx-refresh`,
+    :htmx-header:`hx-push-url`, :htmx-header:`hx-reselect`, …) by merging
+    it into a new dict when you build the framework response::
+
+        if result := form.partial():
+            return Response(
+                result.body,
+                headers={**result.headers, "HX-Trigger": "saved"},
+            )
+
+    The mapping may be read-only, so do not assign into it.
+    """
+
+
+@dataclass(slots=True)
+class _HtmxMutation:
+    """Render plan of one request: the targets to swap, a primary override, OOB extras.
+
+    Dispatch records the targets and the callback results. The plan applies
+    the callback return-value contract (see the API reference).
+    """
+
+    targets: list[Any] = field(default_factory=list)
+    primary_override: Markup | None = None
+    primary_field: Any = None
+    oob_extras: list[Any] = field(default_factory=list)
+    selector_dispatched: bool = False
+
+    @property
+    def dispatched(self) -> bool:
+        """Whether a trigger fired and left something to render."""
+        return bool(
+            self.targets
+            or self.primary_override is not None
+            or self.primary_field is not None
+            or self.selector_dispatched
+        )
+
+    def add_result(self, result: Any) -> None:
+        """Record a callback's return value.
+
+        Check for a Field before an iterable: SelectFieldBase and FieldList are
+        iterable too.
+        """
+        if result is None:
+            return
+
+        if isinstance(result, Field):
+            self.primary_field = result
+            return
+
+        if isinstance(result, (str, Markup)):
+            self.primary_override = Markup(result)
+            return
+
+        items = list(result)
+        if not items:
+            return
+
+        primary, *rest = items
+        if isinstance(primary, (str, Markup)):
+            self.primary_override = Markup(primary)
+        elif isinstance(primary, Field):
+            self.primary_field = primary
+
+        # primary is None → default render kept (no override set).
+        self.oob_extras.extend(rest)
+
+    def split_targets(self) -> tuple[Any, list[Any]]:
+        """Return the primary field, if any, and the targets rendered out-of-band.
+
+        A callback override replaces ``targets[0]``, unless a selector was
+        dispatched: then every target is out-of-band.
+        """
+        if self.primary_override is None and self.primary_field is None:
+            return (self.targets[0] if self.targets else None), self.targets[1:]
+
+        rest = self.targets if self.selector_dispatched else self.targets[1:]
+        return self.primary_field, [t for t in rest if t is not self.primary_field]
+
+
+class _OuterTagParser(HTMLParser):
+    """Locate the first opening tag of a fragment.
+
+    ``tag`` stays ``None`` when the fragment has no tag. ``end`` is the
+    offset just past the tag's ``>``.
+    """
+
+    def __init__(self, html: str) -> None:
+        super().__init__()
+        self.tag: str | None = None
+        self.attrs: dict[str, str | None] = {}
+        self.end = 0
+        # getpos() counts lines on "\n" only, unlike str.splitlines().
+        self._lines = html.split("\n")
+        self.feed(html)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if self.tag is not None:
+            return
+
+        self.tag = tag
+        self.attrs = dict(attrs)
+        lineno, col = self.getpos()
+        start = sum(len(line) + 1 for line in self._lines[: lineno - 1]) + col
+        self.end = start + len(self.get_starttag_text() or "")
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self.handle_starttag(tag, attrs)
+
+
+def _extract_outer_id(html: str) -> str | None:
+    """Return the ``id`` of the first opening tag in ``html``, if any."""
+    return _OuterTagParser(html).attrs.get("id") or None
+
+
+def _with_swap_oob(html: str) -> str:
+    """Add ``hx-swap-oob="outerHTML"`` to the outer element of an OOB fragment.
+
+    Left untouched: a fragment that already sets ``hx-swap-oob``, and a
+    <template> wrapper. Raise ValueError when the outer element has no id.
+    """
+    outer = _OuterTagParser(html)
+    if outer.tag is None or outer.tag == "template":
+        return html
+
+    if "hx-swap-oob" in outer.attrs or "data-hx-swap-oob" in outer.attrs:
+        return html
+
+    if not outer.attrs.get("id"):
+        raise ValueError(
+            f"An out-of-band HTML fragment needs an id on its outer element: {html!r}"
+        )
+
+    head = html[: outer.end]
+    close = "/>" if head.endswith("/>") else ">"
+    head = head[: -len(close)].rstrip()
+    return f'{head} hx-swap-oob="outerHTML"{close}{html[outer.end :]}'
+
+
+def _render_mutation_target(field: Any, *, oob: bool) -> str:
+    """Render one field for a partial response, through its wrapper.
+
+    An out-of-band field gets ``hx-swap-oob`` on the outer element of its
+    rendering, so the whole wrapper is swapped. A ``hide_value`` widget
+    (PasswordInput) shows the typed value during this render, so the swap
+    does not erase it.
+    """
+    html = _render_revealed(field)
+    return _with_swap_oob(html) if oob else html
+
+
+def _render_revealed(field: Any) -> str:
+    """Render ``field``, with the value of a ``hide_value`` widget shown."""
+    widget = getattr(field, "widget", None)
+    if not (getattr(widget, "hide_value", False) and field.data):
+        return str(field.meta.render_field(field, {}))
+
+    # The widget is shared by every field of the class: reveal a copy.
+    field.widget = copy(widget)
+    field.widget.hide_value = False
+    try:
+        return str(field.meta.render_field(field, {}))
+    finally:
+        field.widget = widget
+
+
+def _render_oob(form: HtmxFormMixin, extras: list[Any]) -> Markup:
+    """Render out-of-band extras, each once.
+
+    Fields are deduplicated by identity, HTML fragments by outer id.
+    """
+    html = Markup("")
+    seen: set[Any] = set()
+    for extra in extras:
+        is_html = isinstance(extra, (str, Markup))
+        key = _extract_outer_id(str(extra)) if is_html else id(extra)
+        if key is not None and key in seen:
+            continue
+
+        seen.add(key)
+        if is_html:
+            html += Markup(_with_swap_oob(str(extra)))
+        else:
+            html += Markup(_render_mutation_target(extra, oob=True))
+
+    return html
+
+
+def _render_mutation_response(
+    form: HtmxFormMixin,
+    mutation: _HtmxMutation,
+    request: _HtmxRequestInfo,
+) -> HtmxResponse:
+    """Build the response for a dispatched mutation.
+
+    The primary swap is, in order: the callback's HTML, the callback's field,
+    the first target. The other targets and the callback's extras are
+    out-of-band. Without a primary swap, the body only holds the extras, with
+    ``HX-Reswap: none`` and no ``HX-Retarget``.
+    """
+    response_headers: dict[str, str] = {}
+    primary_field, rest = mutation.split_targets()
+    # Keep the body a Markup: ``Markup.__radd__`` escapes a plain ``str``.
+    if mutation.primary_override is not None:
+        body = mutation.primary_override
+    elif primary_field is not None:
+        body = Markup(_render_mutation_target(primary_field, oob=False))
+    else:
+        oob = _render_oob(form, rest + mutation.oob_extras)
+        return HtmxResponse(body=str(oob), headers={"HX-Reswap": "none"})
+
+    body += _render_oob(form, rest + mutation.oob_extras)
+    if retarget := _compute_retarget(str(body), request):
+        response_headers["HX-Retarget"] = retarget
+
+    return HtmxResponse(body=str(body), headers=response_headers)
+
+
+def _compute_partial(
+    form: HtmxFormMixin,
+    headers: Mapping[str, str] | None,
+) -> HtmxResponse | None:
+    """Render the mutation plan, or a datalist refresh.
+
+    Return ``None`` for a non-htmx or boosted request, or when there is
+    nothing to render.
+    """
+    request = _parse_request(headers)
+    if not request.htmx or request.boosted:
+        return None
+
+    mutation = getattr(form, "_htmx_mutation", None)
+    if mutation is not None and mutation.dispatched:
+        return _render_mutation_response(form, mutation, request)
+
+    return _compute_datalist_partial(form, request)
+
+
+def _compute_datalist_partial(
+    form: HtmxFormMixin,
+    request: _HtmxRequestInfo,
+) -> HtmxResponse | None:
+    """Render the datalist that sent the request, alone.
+
+    Its ``hx-select`` picks the ``<option>`` children. No validation runs.
+    """
+    field = form._htmx_resolve_datalist(request.source_id)
+    if field is None:
+        return None
+
+    return HtmxResponse(body=str(field.datalist()), headers={})
+
+
+def _compute_retarget(body: str, request: _HtmxRequestInfo) -> str | None:
+    """Return an ``hx-retarget`` selector for the fragment's outer id.
+
+    ``None`` when the fragment has no outer id, or when htmx already
+    targets that element.
+    """
+    if not (outer_id := _extract_outer_id(body)):
+        return None
+
+    if request.target_id == outer_id:
+        return None
+
+    return f"#{outer_id}"