pywebview-htmx 0.3.1__tar.gz → 0.4.1__tar.gz

{pywebview_htmx-0.3.1 → pywebview_htmx-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.3.1
+Version: 0.4.1
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -120,12 +120,14 @@ The skill includes:
 ## Quick Start
 
 ```python
+from html import escape
+
 from pywebview_htmx import create_window
 
 
 class API:
     def greeting(self, params: dict) -> str:
-        name = params.get("name", "world")
+        name = escape(str(params.get("name", "world")))
         return f"<p>Hello, {name}!</p>"
 
 
@@ -229,6 +231,12 @@ DOM event name to bind. Default is `click`.
 <div py-call="show_tip" py-trigger="mouseenter">...</div>
 ```
 
+When the runtime handles a native action that would leave or destructively
+change the current document, it prevents that default action. This includes
+form submission, link navigation, and submit/reset controls associated with a
+form. Ordinary buttons and the native state changes of checkboxes, radio
+buttons, and labels are preserved.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -261,6 +269,8 @@ Unknown value falls back to `innerHTML`.
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
 If missing, empty, invalid, or unresolvable, the triggering element is used.
+The selector is resolved when each accepted request starts, so replacement
+markup can provide the wait target for later requests.
 
 ### `py-policy` (optional)
 
@@ -279,6 +289,11 @@ Per-element concurrency override. If omitted, the global
 - `settleDelay` (ms, default: `20`)
 - `requestPolicy` (`"latest-wins"` default, or `"drop"`)
 
+Runtime defaults are read for each accepted request. An element's explicit
+`py-swap` continues to override `defaultSwapStyle`; otherwise, changing
+`defaultSwapStyle` affects its next request even when the element is already
+bound.
+
 Example:
 
 ```js
@@ -297,21 +312,39 @@ window.pywebviewHtmx.config.settleDelay = 50;
 - `py:ignored` (when `requestPolicy="drop"` and request is in flight)
 - `py:error`
 
+These lifecycle events are observational and non-cancelable. Calling
+`preventDefault()` on them does not change request or swap behavior. Every
+`py:error` event includes `event.detail.stale`, a boolean indicating whether a
+newer request had already been issued in the same request scope when the error
+was emitted. Errors from stale requests remain observable even though stale
+successful responses do not update the DOM.
+
+`event.detail.element` identifies the original control. If that control has
+been removed, the runtime dispatches the error on `document.body` so application
+listeners can still receive it.
+
 Example:
 
 ```js
 document.body.addEventListener("py:error", (event) => {
-  console.error("pywebview-htmx error", event.detail.error);
+  console.error("pywebview-htmx error", {
+    error: event.detail.error,
+    stale: event.detail.stale,
+  });
 });
 ```
 
 ## Concurrency Behavior
 
-`pywebview-htmx` tracks request state by resolved target. Controls that share
-the same `py-target` coordinate request ordering and `drop` behavior. Controls
+For a nonempty `py-target`, `pywebview-htmx` scopes request state by its
+normalized selector string. Controls with the same selector coordinate request
+ordering and `drop` behavior even when a swap replaces the matching DOM node.
+Selector state is discarded after its in-flight requests finish. Controls
 without `py-target` use the triggering element as their request state scope.
-Loading state is counted separately per resolved `py-wait` target so shared
-spinners stay active until all in-flight requests finish.
+
+The `py-wait` selector is resolved for each accepted request. Loading state is
+counted separately per resolved wait element, so a shared spinner stays active
+until every request using that particular element finishes.
 
 ### `latest-wins` (default)
 
@@ -346,10 +379,7 @@ Set `theme=None` to disable automatic theme injection.
 
 ### Built-in Component Classes
 
-The bundled CSS supports both `pyh-*` classes and compatibility aliases used by
-the demo (`.hero`, `.demo-card`, `.btn`, etc.).
-
-Recommended canonical classes:
+The bundled CSS exposes canonical `pyh-*` component classes:
 
 - Layout: `.pyh-shell`, `.pyh-hero`, `.pyh-grid`, `.pyh-card`
 - Controls: `.pyh-btn`, `.pyh-btn-primary`, `.pyh-btn-secondary`, `.pyh-btn-ghost`, `.pyh-btn-danger`

{pywebview_htmx-0.3.1 → pywebview_htmx-0.4.1}/README.md

@@ -80,12 +80,14 @@ The skill includes:
 ## Quick Start
 
 ```python
+from html import escape
+
 from pywebview_htmx import create_window
 
 
 class API:
     def greeting(self, params: dict) -> str:
-        name = params.get("name", "world")
+        name = escape(str(params.get("name", "world")))
         return f"<p>Hello, {name}!</p>"
 
 
@@ -189,6 +191,12 @@ DOM event name to bind. Default is `click`.
 <div py-call="show_tip" py-trigger="mouseenter">...</div>
 ```
 
+When the runtime handles a native action that would leave or destructively
+change the current document, it prevents that default action. This includes
+form submission, link navigation, and submit/reset controls associated with a
+form. Ordinary buttons and the native state changes of checkboxes, radio
+buttons, and labels are preserved.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -221,6 +229,8 @@ Unknown value falls back to `innerHTML`.
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
 If missing, empty, invalid, or unresolvable, the triggering element is used.
+The selector is resolved when each accepted request starts, so replacement
+markup can provide the wait target for later requests.
 
 ### `py-policy` (optional)
 
@@ -239,6 +249,11 @@ Per-element concurrency override. If omitted, the global
 - `settleDelay` (ms, default: `20`)
 - `requestPolicy` (`"latest-wins"` default, or `"drop"`)
 
+Runtime defaults are read for each accepted request. An element's explicit
+`py-swap` continues to override `defaultSwapStyle`; otherwise, changing
+`defaultSwapStyle` affects its next request even when the element is already
+bound.
+
 Example:
 
 ```js
@@ -257,21 +272,39 @@ window.pywebviewHtmx.config.settleDelay = 50;
 - `py:ignored` (when `requestPolicy="drop"` and request is in flight)
 - `py:error`
 
+These lifecycle events are observational and non-cancelable. Calling
+`preventDefault()` on them does not change request or swap behavior. Every
+`py:error` event includes `event.detail.stale`, a boolean indicating whether a
+newer request had already been issued in the same request scope when the error
+was emitted. Errors from stale requests remain observable even though stale
+successful responses do not update the DOM.
+
+`event.detail.element` identifies the original control. If that control has
+been removed, the runtime dispatches the error on `document.body` so application
+listeners can still receive it.
+
 Example:
 
 ```js
 document.body.addEventListener("py:error", (event) => {
-  console.error("pywebview-htmx error", event.detail.error);
+  console.error("pywebview-htmx error", {
+    error: event.detail.error,
+    stale: event.detail.stale,
+  });
 });
 ```
 
 ## Concurrency Behavior
 
-`pywebview-htmx` tracks request state by resolved target. Controls that share
-the same `py-target` coordinate request ordering and `drop` behavior. Controls
+For a nonempty `py-target`, `pywebview-htmx` scopes request state by its
+normalized selector string. Controls with the same selector coordinate request
+ordering and `drop` behavior even when a swap replaces the matching DOM node.
+Selector state is discarded after its in-flight requests finish. Controls
 without `py-target` use the triggering element as their request state scope.
-Loading state is counted separately per resolved `py-wait` target so shared
-spinners stay active until all in-flight requests finish.
+
+The `py-wait` selector is resolved for each accepted request. Loading state is
+counted separately per resolved wait element, so a shared spinner stays active
+until every request using that particular element finishes.
 
 ### `latest-wins` (default)
 
@@ -306,10 +339,7 @@ Set `theme=None` to disable automatic theme injection.
 
 ### Built-in Component Classes
 
-The bundled CSS supports both `pyh-*` classes and compatibility aliases used by
-the demo (`.hero`, `.demo-card`, `.btn`, etc.).
-
-Recommended canonical classes:
+The bundled CSS exposes canonical `pyh-*` component classes:
 
 - Layout: `.pyh-shell`, `.pyh-hero`, `.pyh-grid`, `.pyh-card`
 - Controls: `.pyh-btn`, `.pyh-btn-primary`, `.pyh-btn-secondary`, `.pyh-btn-ghost`, `.pyh-btn-danger`

{pywebview_htmx-0.3.1 → pywebview_htmx-0.4.1}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.3.1"
+version = "0.4.1"
 
 [project.license]
 file = "LICENSE"
@@ -32,22 +32,14 @@ requires = [
 ]
 build-backend = "pdm.backend"
 
-[tool.pdm]
-distribution = true
-
-[tool.pdm.version]
-source = "scm"
-
-[tool.pdm.build]
-package-dir = "src"
-includes = [
-    "src/pywebview_htmx",
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.15.19",
+    "playwright>=1.61.0",
+    "pytest-playwright>=0.8.0",
 ]
 
-[tool.pdm.scripts]
-test = "pytest"
-lint = "ruff check ."
-
 [tool.pytest.ini_options]
 testpaths = [
     "tests",
@@ -63,8 +55,19 @@ select = [
     "W",
 ]
 
-[dependency-groups]
-dev = [
-    "pytest>=9.0.3",
-    "ruff>=0.15.17",
+[tool.pdm]
+distribution = true
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.build]
+package-dir = "src"
+includes = [
+    "src/pywebview_htmx",
 ]
+
+[tool.pdm.scripts]
+test = "pytest"
+lint = "ruff check ."
+install-browser = "playwright install chromium"

{pywebview_htmx-0.3.1 → pywebview_htmx-0.4.1}/src/pywebview_htmx/static/runtime.js

@@ -7,8 +7,10 @@
     settleDelay: 20,
     requestPolicy: "latest-wins",
   };
-  const requestState = new WeakMap();
+  const selfRequestState = new WeakMap();
+  const targetedRequestState = new Map();
   const waitState = new WeakMap();
+  const boundElements = new WeakSet();
 
   function $(selector, root = document) {
     if (!selector) return null;
@@ -23,7 +25,7 @@
   function triggerEvent(target, eventName, detail = {}) {
     const event = new CustomEvent(eventName, {
       bubbles: true,
-      cancelable: true,
+      cancelable: false,
       detail,
     });
     target.dispatchEvent(event);
@@ -132,20 +134,21 @@
     return await func(params);
   }
 
-  function getRequestState(key) {
-    let state = requestState.get(key);
+  function getRequestScope(element, targetSelector) {
+    const key = targetSelector || element;
+    const store = targetSelector ? targetedRequestState : selfRequestState;
+    let state = store.get(key);
     if (!state) {
       state = { lastIssued: 0, inFlightCount: 0 };
-      requestState.set(key, state);
+      store.set(key, state);
     }
-    return state;
+    return { key, state, store };
   }
 
-  function getRequestStateKey(element, targetSelector) {
-    if (!targetSelector) {
-      return element;
+  function releaseRequestScope(scope) {
+    if (scope.state.inFlightCount === 0 && scope.store.get(scope.key) === scope.state) {
+      scope.store.delete(scope.key);
     }
-    return $(targetSelector) || element;
   }
 
   function addWaiting(waitTarget) {
@@ -164,8 +167,24 @@
     waitState.set(waitTarget, count);
   }
 
-  function shouldPreventDefault(eventName) {
-    return eventName === "submit";
+  function shouldPreventDefault(element, eventName) {
+    if (eventName === "submit") {
+      return true;
+    }
+    if (eventName !== "click") {
+      return false;
+    }
+
+    if ((element.tagName === "A" || element.tagName === "AREA") && element.hasAttribute("href")) {
+      return true;
+    }
+    if (element.tagName === "BUTTON" && element.form) {
+      return element.type !== "button";
+    }
+    if (element.tagName === "INPUT" && element.form) {
+      return ["image", "reset", "submit"].includes(element.type);
+    }
+    return false;
   }
 
   function getRequestPolicy(element) {
@@ -188,29 +207,28 @@
     elements.push(...root.querySelectorAll("[py-call]"));
 
     elements.forEach((element) => {
-      if (element.getAttribute("data-pywebview-bound") === "true") {
+      if (boundElements.has(element)) {
         return;
       }
-      element.setAttribute("data-pywebview-bound", "true");
 
       const functionName = element.getAttribute("py-call");
       const eventName = element.getAttribute("py-trigger") || "click";
-      const targetSelector = element.getAttribute("py-target");
-      const swapStyle = element.getAttribute("py-swap") || config.defaultSwapStyle;
-      const waitTarget = getWaitTarget(element);
+      const targetSelector = (element.getAttribute("py-target") || "").trim() || null;
 
       if (!functionName) {
         console.warn("PyWebview HTMX: py-call is empty", element);
         return;
       }
+      boundElements.add(element);
 
       element.addEventListener(eventName, async (event) => {
-        if (shouldPreventDefault(eventName) && event.cancelable) {
+        if (shouldPreventDefault(element, eventName) && event.cancelable) {
           event.preventDefault();
         }
 
         const params = buildRequestParams(element, eventName, event);
-        const state = getRequestState(getRequestStateKey(element, targetSelector));
+        const scope = getRequestScope(element, targetSelector);
+        const state = scope.state;
         const requestPolicy = getRequestPolicy(element);
         if (requestPolicy === "drop" && state.inFlightCount > 0) {
           triggerEvent(element, "py:ignored", { reason: "in-flight" });
@@ -227,6 +245,8 @@
           requestId,
         });
 
+        const swapStyle = element.getAttribute("py-swap") || config.defaultSwapStyle;
+        const waitTarget = getWaitTarget(element);
         addWaiting(waitTarget);
 
         try {
@@ -238,7 +258,7 @@
             throw new Error("PyWebview HTMX: Python API methods must return an HTML string");
           }
 
-          const target = targetSelector ? $(targetSelector) : element;
+          let target = targetSelector ? $(targetSelector) : element;
           if (!target) {
             console.warn("PyWebview HTMX: target element not found", targetSelector);
             return;
@@ -252,6 +272,12 @@
             return;
           }
 
+          target = targetSelector ? $(targetSelector) : element;
+          if (!target || !target.isConnected) {
+            console.warn("PyWebview HTMX: target element not found", targetSelector);
+            return;
+          }
+
           const processRoot = pySwap(target, response, swapStyle);
           const afterSwapTarget =
             swapStyle === "outerHTML"
@@ -265,9 +291,16 @@
           }
         } catch (error) {
           console.error("PyWebview HTMX: error calling Python function", error);
-          triggerEvent(element, "py:error", { error, requestId });
+          const errorTarget = element.isConnected ? element : document.body || document;
+          triggerEvent(errorTarget, "py:error", {
+            element,
+            error,
+            requestId,
+            stale: requestId !== state.lastIssued,
+          });
         } finally {
           state.inFlightCount = Math.max(0, state.inFlightCount - 1);
+          releaseRequestScope(scope);
           removeWaiting(waitTarget);
         }
       });