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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.3.0
+Version: 0.4.0
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -35,7 +35,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.14
-Requires-Dist: pywebview>=6.1
+Requires-Dist: pywebview>=6.2.1
 Description-Content-Type: text/markdown
 
 # pywebview-htmx
@@ -84,6 +84,11 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Maintainer Docs
+
+For maintainer and agent-facing repository guidance, see
+[`docs/index.md`](docs/index.md).
+
 ## Agent Skill
 
 This repository includes an installable coding-agent skill at
@@ -115,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>"
 
 
@@ -224,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.
@@ -255,7 +268,9 @@ Unknown value falls back to `innerHTML`.
 ### `py-wait` (optional)
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
-If missing/empty/unresolvable, the triggering element is used.
+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)
 
@@ -274,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
@@ -292,27 +312,45 @@ 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.
+
 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
 
-Per trigger element, `pywebview-htmx` tracks request state.
+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.
+
+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)
 
-Multiple rapid requests are allowed; stale responses are ignored.
-Only latest request updates the DOM.
+Multiple rapid requests are allowed; stale responses in the same request state
+scope are ignored. Only the latest request for that scope updates the DOM.
 
 ### `drop`
 
-If a request is already in flight for that element, new triggers are ignored and
-`py:ignored` is emitted.
+If a request is already in flight for the same request state scope, new triggers
+are ignored and `py:ignored` is emitted.
 
 ## Dynamic Content Re-processing
 
@@ -337,10 +375,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.0 → pywebview_htmx-0.4.0}/README.md

@@ -44,6 +44,11 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Maintainer Docs
+
+For maintainer and agent-facing repository guidance, see
+[`docs/index.md`](docs/index.md).
+
 ## Agent Skill
 
 This repository includes an installable coding-agent skill at
@@ -75,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>"
 
 
@@ -184,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.
@@ -215,7 +228,9 @@ Unknown value falls back to `innerHTML`.
 ### `py-wait` (optional)
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
-If missing/empty/unresolvable, the triggering element is used.
+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)
 
@@ -234,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
@@ -252,27 +272,45 @@ 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.
+
 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
 
-Per trigger element, `pywebview-htmx` tracks request state.
+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.
+
+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)
 
-Multiple rapid requests are allowed; stale responses are ignored.
-Only latest request updates the DOM.
+Multiple rapid requests are allowed; stale responses in the same request state
+scope are ignored. Only the latest request for that scope updates the DOM.
 
 ### `drop`
 
-If a request is already in flight for that element, new triggers are ignored and
-`py:ignored` is emitted.
+If a request is already in flight for the same request state scope, new triggers
+are ignored and `py:ignored` is emitted.
 
 ## Dynamic Content Re-processing
 
@@ -297,10 +335,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.0 → pywebview_htmx-0.4.0}/pyproject.toml

@@ -6,7 +6,7 @@ authors = [
     { name = "B.T. Franklin", email = "brandon.franklin@gmail.com" },
 ]
 dependencies = [
-    "pywebview>=6.1",
+    "pywebview>=6.2.1",
 ]
 requires-python = ">=3.14"
 readme = "README.md"
@@ -21,33 +21,25 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.3.0"
+version = "0.4.0"
 
 [project.license]
 file = "LICENSE"
 
 [build-system]
 requires = [
-    "pdm-backend",
+    "pdm-backend>=2.4.9",
 ]
 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.2",
-    "ruff>=0.15.4",
+[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.4.0/src/pywebview_htmx/py.typed

@@ -0,0 +1 @@
+

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

@@ -7,17 +7,24 @@
     settleDelay: 20,
     requestPolicy: "latest-wins",
   };
-  const requestState = new WeakMap();
+  const selfRequestState = new WeakMap();
+  const targetedRequestState = new Map();
+  const waitState = new WeakMap();
 
   function $(selector, root = document) {
     if (!selector) return null;
-    return root.querySelector(selector);
+    try {
+      return root.querySelector(selector);
+    } catch (error) {
+      console.warn("PyWebview HTMX: invalid selector", selector, error);
+      return null;
+    }
   }
 
   function triggerEvent(target, eventName, detail = {}) {
     const event = new CustomEvent(eventName, {
       bubbles: true,
-      cancelable: true,
+      cancelable: false,
       detail,
     });
     target.dispatchEvent(event);
@@ -126,17 +133,57 @@
     return await func(params);
   }
 
-  function getRequestState(element) {
-    let state = requestState.get(element);
+  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(element, state);
+      store.set(key, state);
+    }
+    return { key, state, store };
+  }
+
+  function releaseRequestScope(scope) {
+    if (scope.state.inFlightCount === 0 && scope.store.get(scope.key) === scope.state) {
+      scope.store.delete(scope.key);
     }
-    return state;
   }
 
-  function shouldPreventDefault(eventName) {
-    return eventName === "submit";
+  function addWaiting(waitTarget) {
+    const count = (waitState.get(waitTarget) || 0) + 1;
+    waitState.set(waitTarget, count);
+    waitTarget.classList.add("py-waiting");
+  }
+
+  function removeWaiting(waitTarget) {
+    const count = Math.max(0, (waitState.get(waitTarget) || 0) - 1);
+    if (count === 0) {
+      waitState.delete(waitTarget);
+      waitTarget.classList.remove("py-waiting");
+      return;
+    }
+    waitState.set(waitTarget, count);
+  }
+
+  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) {
@@ -166,9 +213,7 @@
 
       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);
@@ -176,12 +221,13 @@
       }
 
       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(element);
+        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" });
@@ -198,7 +244,9 @@
           requestId,
         });
 
-        waitTarget.classList.add("py-waiting");
+        const swapStyle = element.getAttribute("py-swap") || config.defaultSwapStyle;
+        const waitTarget = getWaitTarget(element);
+        addWaiting(waitTarget);
 
         try {
           const response = await invokePython(functionName, params);
@@ -236,12 +284,15 @@
           }
         } catch (error) {
           console.error("PyWebview HTMX: error calling Python function", error);
-          triggerEvent(element, "py:error", { error, requestId });
+          triggerEvent(element, "py:error", {
+            error,
+            requestId,
+            stale: requestId !== state.lastIssued,
+          });
         } finally {
           state.inFlightCount = Math.max(0, state.inFlightCount - 1);
-          if (state.inFlightCount === 0) {
-            waitTarget.classList.remove("py-waiting");
-          }
+          releaseRequestScope(scope);
+          removeWaiting(waitTarget);
         }
       });
     });