pywebview-htmx 0.2.1__tar.gz → 0.3.0__tar.gz

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.2.1
+Version: 0.3.0
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -84,6 +84,34 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Agent Skill
+
+This repository includes an installable coding-agent skill at
+`skills/use-pywebview-htmx/`.
+
+The folder in this repository is the source for a skill that tools such as
+[`npx skills`](https://skills.sh/) can discover and install from GitHub.
+
+List the available skill from this repository:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --list --full-depth
+```
+
+Install just this skill:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --skill use-pywebview-htmx
+```
+
+Other skill installers can consume the same skill folder from this repository.
+The skill includes:
+
+- the core usage workflow
+- a concise contract reference
+- implementation patterns
+- troubleshooting guidance
+
 ## Quick Start
 
 ```python
@@ -117,6 +145,18 @@ create_window("Quickstart", html, js_api=API())
 You do **not** manually include `runtime.js` when using `create_window()`;
 it is injected automatically.
 
+## Important Differences From HTMX
+
+- There is no HTTP request layer. `pywebview-htmx` calls a Python method on
+  `window.pywebview.api` directly.
+- Python handlers should return an HTML string fragment. Returning objects or
+  other data types is treated as an error.
+- For ordinary buttons/links, params still come from `data-py-params`.
+- For `<form py-trigger="submit">`, named fields are serialized automatically
+  and merged over `data-py-params`.
+- Returned HTML is inserted directly into the DOM, so escape untrusted values
+  before returning markup.
+
 ## API Reference (Python)
 
 ### `create_window(title, html, js_api=None, theme="aurora", start=True, **kwargs)`
@@ -143,6 +183,18 @@ Returns the bundled JavaScript runtime as a string.
 
 Injects the runtime script tag into an HTML string (idempotent).
 
+### `encode_params_attr(params)`
+
+Returns HTML-escaped JSON that is safe to place in a `data-py-params`
+attribute.
+
+```python
+from pywebview_htmx import encode_params_attr
+
+payload = encode_params_attr({"user_id": 42, "mode": "full"})
+button = f'<button data-py-params="{payload}">Load user</button>'
+```
+
 ### Theme helpers
 
 - `list_themes()` -> sorted list of available themes
@@ -183,6 +235,8 @@ JSON payload passed to Python method.
 Notes:
 - If missing, params default to `{}`.
 - Invalid JSON logs an error and falls back to `{}`.
+- For submit-triggered forms, named form fields are serialized automatically and
+  merged over this payload.
 
 ### `py-target` (optional)
 
@@ -203,6 +257,14 @@ Unknown value falls back to `innerHTML`.
 CSS selector of element receiving `.py-waiting` while request is in flight.
 If missing/empty/unresolvable, the triggering element is used.
 
+### `py-policy` (optional)
+
+Per-element concurrency override. If omitted, the global
+`window.pywebviewHtmx.config.requestPolicy` value is used.
+
+- `latest-wins`
+- `drop`
+
 ## Runtime Config (JavaScript)
 
 `window.pywebviewHtmx.config` includes:
@@ -297,7 +359,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 1: Form submit to Python
 
 - Use `py-trigger="submit"` on `<form>`
-- Keep `data-py-params` in sync from form inputs (via JS)
+- Give fields `name` attributes so they can be serialized
+- Use `data-py-params` only for extra static values you want merged in
 - `py-target` a result card/summary region
 
 ### Pattern 2: Append activity/log rows
@@ -308,7 +371,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 3: Replace full component
 
 - Use `py-swap="outerHTML"`
-- Return full replacement markup with same outer id/selector
+- Return full replacement markup with the same outer id/selector if future
+  interactions should keep targeting that component
 
 ### Pattern 4: Theme switch from Python
 
@@ -331,6 +395,7 @@ Check:
 - method returns a string of HTML
 - no JSON parse error in `data-py-params`
 - `py-target` selector exists
+- for forms, fields have `name` attributes
 
 ### "New buttons in swapped HTML do not work"
 
@@ -345,6 +410,21 @@ window.pywebviewHtmx.process(document.body);
 
 Style `.py-waiting` globally and/or point `py-wait` at a dedicated element.
 
+### "I got a Python API return type error"
+
+`pywebview-htmx` expects handlers to return an HTML string fragment. Convert
+structured data into markup before returning it.
+
+## Common Mistakes
+
+- Returning dicts/lists instead of HTML strings
+- Forgetting to escape untrusted values before interpolating into markup
+- Omitting `name` attributes on form fields and expecting them to serialize
+- Using `py-swap="outerHTML"` but not preserving the target component's
+  selector/id
+- Manually mutating the DOM outside of `pywebview-htmx` swaps without calling
+  `window.pywebviewHtmx.process(...)`
+
 ## Demo
 
 Run the full feature showcase:

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/README.md

@@ -44,6 +44,34 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Agent Skill
+
+This repository includes an installable coding-agent skill at
+`skills/use-pywebview-htmx/`.
+
+The folder in this repository is the source for a skill that tools such as
+[`npx skills`](https://skills.sh/) can discover and install from GitHub.
+
+List the available skill from this repository:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --list --full-depth
+```
+
+Install just this skill:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --skill use-pywebview-htmx
+```
+
+Other skill installers can consume the same skill folder from this repository.
+The skill includes:
+
+- the core usage workflow
+- a concise contract reference
+- implementation patterns
+- troubleshooting guidance
+
 ## Quick Start
 
 ```python
@@ -77,6 +105,18 @@ create_window("Quickstart", html, js_api=API())
 You do **not** manually include `runtime.js` when using `create_window()`;
 it is injected automatically.
 
+## Important Differences From HTMX
+
+- There is no HTTP request layer. `pywebview-htmx` calls a Python method on
+  `window.pywebview.api` directly.
+- Python handlers should return an HTML string fragment. Returning objects or
+  other data types is treated as an error.
+- For ordinary buttons/links, params still come from `data-py-params`.
+- For `<form py-trigger="submit">`, named fields are serialized automatically
+  and merged over `data-py-params`.
+- Returned HTML is inserted directly into the DOM, so escape untrusted values
+  before returning markup.
+
 ## API Reference (Python)
 
 ### `create_window(title, html, js_api=None, theme="aurora", start=True, **kwargs)`
@@ -103,6 +143,18 @@ Returns the bundled JavaScript runtime as a string.
 
 Injects the runtime script tag into an HTML string (idempotent).
 
+### `encode_params_attr(params)`
+
+Returns HTML-escaped JSON that is safe to place in a `data-py-params`
+attribute.
+
+```python
+from pywebview_htmx import encode_params_attr
+
+payload = encode_params_attr({"user_id": 42, "mode": "full"})
+button = f'<button data-py-params="{payload}">Load user</button>'
+```
+
 ### Theme helpers
 
 - `list_themes()` -> sorted list of available themes
@@ -143,6 +195,8 @@ JSON payload passed to Python method.
 Notes:
 - If missing, params default to `{}`.
 - Invalid JSON logs an error and falls back to `{}`.
+- For submit-triggered forms, named form fields are serialized automatically and
+  merged over this payload.
 
 ### `py-target` (optional)
 
@@ -163,6 +217,14 @@ Unknown value falls back to `innerHTML`.
 CSS selector of element receiving `.py-waiting` while request is in flight.
 If missing/empty/unresolvable, the triggering element is used.
 
+### `py-policy` (optional)
+
+Per-element concurrency override. If omitted, the global
+`window.pywebviewHtmx.config.requestPolicy` value is used.
+
+- `latest-wins`
+- `drop`
+
 ## Runtime Config (JavaScript)
 
 `window.pywebviewHtmx.config` includes:
@@ -257,7 +319,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 1: Form submit to Python
 
 - Use `py-trigger="submit"` on `<form>`
-- Keep `data-py-params` in sync from form inputs (via JS)
+- Give fields `name` attributes so they can be serialized
+- Use `data-py-params` only for extra static values you want merged in
 - `py-target` a result card/summary region
 
 ### Pattern 2: Append activity/log rows
@@ -268,7 +331,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 3: Replace full component
 
 - Use `py-swap="outerHTML"`
-- Return full replacement markup with same outer id/selector
+- Return full replacement markup with the same outer id/selector if future
+  interactions should keep targeting that component
 
 ### Pattern 4: Theme switch from Python
 
@@ -291,6 +355,7 @@ Check:
 - method returns a string of HTML
 - no JSON parse error in `data-py-params`
 - `py-target` selector exists
+- for forms, fields have `name` attributes
 
 ### "New buttons in swapped HTML do not work"
 
@@ -305,6 +370,21 @@ window.pywebviewHtmx.process(document.body);
 
 Style `.py-waiting` globally and/or point `py-wait` at a dedicated element.
 
+### "I got a Python API return type error"
+
+`pywebview-htmx` expects handlers to return an HTML string fragment. Convert
+structured data into markup before returning it.
+
+## Common Mistakes
+
+- Returning dicts/lists instead of HTML strings
+- Forgetting to escape untrusted values before interpolating into markup
+- Omitting `name` attributes on form fields and expecting them to serialize
+- Using `py-swap="outerHTML"` but not preserving the target component's
+  selector/id
+- Manually mutating the DOM outside of `pywebview-htmx` swaps without calling
+  `window.pywebviewHtmx.process(...)`
+
 ## Demo
 
 Run the full feature showcase:

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.2.1"
+version = "0.3.0"
 
 [project.license]
 file = "LICENSE"

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/src/pywebview_htmx/__init__.py

@@ -1,6 +1,7 @@
 from .runtime import (
     DEFAULT_THEME,
     create_window,
+    encode_params_attr,
     get_runtime_script,
     get_theme_css,
     inject_runtime,
@@ -11,6 +12,7 @@ from .runtime import (
 __all__ = [
     "DEFAULT_THEME",
     "create_window",
+    "encode_params_attr",
     "get_runtime_script",
     "get_theme_css",
     "inject_runtime",

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/src/pywebview_htmx/runtime.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from importlib.resources import files
+import json
 import re
+from html import escape as html_escape
 from typing import Any
 
 import webview
@@ -56,6 +58,14 @@ def get_runtime_script() -> str:
     )
 
 
+def encode_params_attr(params: Any) -> str:
+    """Encode a payload for safe embedding in ``data-py-params``."""
+    return html_escape(
+        json.dumps(params, sort_keys=True),
+        quote=True,
+    )
+
+
 def inject_runtime(html: str) -> str:
     """Inject the runtime script into an HTML string before ``</body>`` when present."""
     if _SCRIPT_TAG_RE.search(html):

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/src/pywebview_htmx/static/runtime.js

@@ -58,6 +58,47 @@
     }
   }
 
+  function mergeParamValue(target, key, value) {
+    if (Object.prototype.hasOwnProperty.call(target, key)) {
+      const existing = target[key];
+      if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        target[key] = [existing, value];
+      }
+      return;
+    }
+    target[key] = value;
+  }
+
+  function serializeForm(form, event) {
+    const params = {};
+    const formData = new FormData(form);
+
+    for (const [key, value] of formData.entries()) {
+      if (typeof File !== "undefined" && value instanceof File) {
+        console.warn("PyWebview HTMX: file inputs are not supported in data-py-params", key);
+        continue;
+      }
+      mergeParamValue(params, key, value);
+    }
+
+    const submitter = event && "submitter" in event ? event.submitter : null;
+    if (submitter && submitter.name) {
+      mergeParamValue(params, submitter.name, submitter.value || "");
+    }
+
+    return params;
+  }
+
+  function buildRequestParams(element, eventName, event) {
+    const params = parseParams(element);
+    if (element.tagName !== "FORM" || eventName !== "submit") {
+      return params;
+    }
+    return { ...params, ...serializeForm(element, event) };
+  }
+
   function getWaitTarget(element) {
     if (!element.hasAttribute("py-wait")) {
       return element;
@@ -98,12 +139,24 @@
     return eventName === "submit";
   }
 
+  function getRequestPolicy(element) {
+    const policy = element.getAttribute("py-policy") || config.requestPolicy;
+    if (policy === "drop" || policy === "latest-wins") {
+      return policy;
+    }
+    return config.requestPolicy;
+  }
+
   function processPyWebviewHtmxNodes(root = document) {
     if (!root || typeof root.querySelectorAll !== "function") {
       return;
     }
 
-    const elements = root.querySelectorAll("[py-call]");
+    const elements = [];
+    if (root.matches && root.matches("[py-call]")) {
+      elements.push(root);
+    }
+    elements.push(...root.querySelectorAll("[py-call]"));
 
     elements.forEach((element) => {
       if (element.getAttribute("data-pywebview-bound") === "true") {
@@ -127,9 +180,10 @@
           event.preventDefault();
         }
 
-        const params = parseParams(element);
+        const params = buildRequestParams(element, eventName, event);
         const state = getRequestState(element);
-        if (config.requestPolicy === "drop" && state.inFlightCount > 0) {
+        const requestPolicy = getRequestPolicy(element);
+        if (requestPolicy === "drop" && state.inFlightCount > 0) {
           triggerEvent(element, "py:ignored", { reason: "in-flight" });
           return;
         }
@@ -151,6 +205,9 @@
           if (requestId !== state.lastIssued) {
             return;
           }
+          if (typeof response !== "string") {
+            throw new Error("PyWebview HTMX: Python API methods must return an HTML string");
+          }
 
           const target = targetSelector ? $(targetSelector) : element;
           if (!target) {

pywebview_htmx-0.3.0/tests/test_js_contract_ergonomics.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import pytest
+
+TESTED_BEHAVIOR_IDS = set(range(101, 114))
+
+
+def _assert_fragments_present(js_compact: str, fragments: tuple[str, ...]) -> None:
+    for fragment in fragments:
+        assert fragment in js_compact
+
+
+JS_BEHAVIOR_FRAGMENTS: list[tuple[int, tuple[str, ...]]] = [
+    (
+        101,
+        (
+            "function mergeParamValue(target, key, value)",
+            "if (Object.prototype.hasOwnProperty.call(target, key))",
+        ),
+    ),
+    (
+        102,
+        (
+            "function serializeForm(form, event)",
+            "const formData = new FormData(form);",
+        ),
+    ),
+    (
+        103,
+        (
+            'const submitter = event && "submitter" in event ? event.submitter : null;',
+            "submitter.name",
+        ),
+    ),
+    (
+        104,
+        (
+            "value instanceof File",
+            (
+                'console.warn("PyWebview HTMX: file inputs are not supported '
+                'in data-py-params"'
+            ),
+        ),
+    ),
+    (
+        105,
+        (
+            "function buildRequestParams(element, eventName, event)",
+            'if (element.tagName !== "FORM" || eventName !== "submit")',
+            "return { ...params, ...serializeForm(element, event) };",
+        ),
+    ),
+    (
+        106,
+        (
+            "const elements = [];",
+            'if (root.matches && root.matches("[py-call]"))',
+            "elements.push(root);",
+            'elements.push(...root.querySelectorAll("[py-call]"));',
+        ),
+    ),
+    (
+        107,
+        (
+            "function getRequestPolicy(element)",
+            'const policy = element.getAttribute("py-policy") || config.requestPolicy;',
+        ),
+    ),
+    (
+        108,
+        (
+            'policy === "drop" || policy === "latest-wins"',
+            "return config.requestPolicy;",
+        ),
+    ),
+    (
+        109,
+        (
+            "const requestPolicy = getRequestPolicy(element);",
+            'if (requestPolicy === "drop" && state.inFlightCount > 0)',
+        ),
+    ),
+    (
+        110,
+        (
+            "const params = buildRequestParams(element, eventName, event);",
+        ),
+    ),
+    (
+        111,
+        (
+            'if (typeof response !== "string") {',
+            (
+                'throw new Error("PyWebview HTMX: Python API methods must return '
+                'an HTML string")'
+            ),
+        ),
+    ),
+    (
+        112,
+        (
+            'triggerEvent(element, "py:error", { error, requestId });',
+        ),
+    ),
+    (
+        113,
+        (
+            'element.getAttribute("py-policy")',
+        ),
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    ("behavior_id", "fragments"),
+    JS_BEHAVIOR_FRAGMENTS,
+    ids=[f"B{behavior_id}" for behavior_id, _ in JS_BEHAVIOR_FRAGMENTS],
+)
+def test_js_ergonomic_contract_fragments(
+    behavior_id: int,
+    fragments: tuple[str, ...],
+    js_compact: str,
+) -> None:
+    _ = behavior_id
+    _assert_fragments_present(js_compact, fragments)

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.0}/tests/test_js_contract_request_and_swap.py

@@ -23,7 +23,7 @@ JS_BEHAVIOR_FRAGMENTS: list[tuple[int, tuple[str, ...]]] = [
     (74, ("let state = requestState.get(element);", "if (!state) {")),
     (75, ("lastIssued: 0", "state.lastIssued = requestId;")),
     (76, ("inFlightCount: 0", "state.inFlightCount += 1;")),
-    (77, ('config.requestPolicy === "drop"', 'triggerEvent(element, "py:ignored"')),
+    (77, ('requestPolicy === "drop"', 'triggerEvent(element, "py:ignored"')),
     (78, ('triggerEvent(element, "py:trigger"', "requestId,")),
     (79, ('waitTarget.classList.add("py-waiting")',)),
     (80, ("if (requestId !== state.lastIssued) { return; }",)),

pywebview_htmx-0.3.0/tests/test_python_params_attr.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pywebview_htmx import encode_params_attr
+
+
+def test_encode_params_attr_returns_json_string() -> None:
+    encoded = encode_params_attr({"count": 3, "enabled": True})
+    assert encoded == "{"count": 3, "enabled": true}"
+
+
+def test_encode_params_attr_escapes_quotes_and_tags() -> None:
+    encoded = encode_params_attr({"message": '"hi" <b>unsafe</b>'})
+    assert "\\&quot;hi\\&quot;" in encoded
+    assert "&lt;b&gt;unsafe&lt;/b&gt;" in encoded
+
+
+def test_encode_params_attr_is_exported_from_package() -> None:
+    encoded = encode_params_attr({"name": "pywebview-htmx"})
+    assert isinstance(encoded, str)