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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.4.1
+Version: 0.5.0
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -87,7 +87,9 @@ pdm add pywebview-htmx
 ## Maintainer Docs
 
 For maintainer and agent-facing repository guidance, see
-[`docs/index.md`](docs/index.md).
+[`docs/index.md`](docs/index.md). Run `pdm run check` for lint, tests, and
+offline documentation checks. The documentation check requires the native
+`perfect-doc` executable and can run alone with `pdm run check-docs`.
 
 ## Agent Skill
 
@@ -159,7 +161,7 @@ it is injected automatically.
 - 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
+- For forms with `submit`, `input`, or `change` triggers, 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.
@@ -195,6 +197,9 @@ Injects the runtime script tag into an HTML string (idempotent).
 Returns HTML-escaped JSON that is safe to place in a `data-py-params`
 attribute.
 
+Non-finite numbers (`NaN` and positive or negative infinity) raise `ValueError`.
+JSON does not support these values.
+
 ```python
 from pywebview_htmx import encode_params_attr
 
@@ -237,6 +242,9 @@ 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.
 
+A label that contains its control calls Python once per activation. Clicking
+the label text still changes the checkbox or radio state.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -247,8 +255,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
+- Invalid JSON or a value that is not an object emits `py:error`. Python is not called.
+- For forms with `submit`, `input`, or `change` triggers, named fields are serialized automatically and
   merged over this payload.
 
 ### `py-target` (optional)
@@ -288,6 +296,7 @@ Per-element concurrency override. If omitted, the global
 - `swapDelay` (ms, default: `0`)
 - `settleDelay` (ms, default: `20`)
 - `requestPolicy` (`"latest-wins"` default, or `"drop"`)
+- `requestTimeout` (ms, default: `0`; `py-timeout` overrides it per element)
 
 Runtime defaults are read for each accepted request. An element's explicit
 `py-swap` continues to override `defaultSwapStyle`; otherwise, changing
@@ -346,6 +355,9 @@ 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.
 
+The bundled loading styles show `.py-waiting` without blocking pointer input.
+The request policy controls whether another trigger is accepted.
+
 ### `latest-wins` (default)
 
 Multiple rapid requests are allowed; stale responses in the same request state
@@ -356,10 +368,33 @@ scope are ignored. Only the latest request for that scope updates the DOM.
 If a request is already in flight for the same request state scope, new triggers
 are ignored and `py:ignored` is emitted.
 
+### Python Handler Concurrency
+
+`latest-wins` does not cancel Python work. Each accepted call still runs, even
+when its returned HTML is later ignored. PyWebview runs exposed handlers in
+separate threads. Protect shared mutable data with a lock or a database
+transaction when needed.
+
+`drop` applies to the same request scope. It does not prevent calls from other
+scopes from changing the same Python data.
+
+### Bridge Readiness
+
+PyWebview creates the bridge after the document loads. Wait for the
+`pywebviewready` event before starting programmatic calls:
+
+```js
+window.addEventListener("pywebviewready", () => {
+  document.querySelector("#load-button").click();
+});
+```
+
+A call made before the bridge is available emits `py:error`. It is not queued.
+
 ## Dynamic Content Re-processing
 
-After a swap, `pywebview-htmx` automatically scans swapped content for new `py-call`
-elements and binds them. This enables chained interactions in returned fragments
+After a swap, `pywebview-htmx` binds controls in the inserted content. Append
+and outer replacement do not scan existing siblings again. This enables chained interactions in returned fragments
 without manual re-init code.
 
 ## Theme System
@@ -484,3 +519,72 @@ The demo includes:
 ## License
 
 MIT (see [LICENSE](LICENSE)).
+
+## Request deadlines
+
+Set `py-timeout="2000"` for a two-second Python response deadline. The global
+`requestTimeout` default is `0` (no deadline). Values are milliseconds from
+0 to 2147483647. A timeout emits `py:error` with `detail.phase="timeout"` and
+`error.name="TimeoutError"`. The loading indicator stops, and a late response
+cannot change the page. A late Python failure still emits `py:error` with
+`detail.expired=true`.
+
+A deadline does not cancel Python work or retry the call. Under `drop`, the
+scope stays locked until Python finishes. Show the timeout message and let the
+application check the operation's result before another attempt. If Python
+never returns, the lock remains until the page is reloaded; reloading does not
+prove that the operation was cancelled. Use `latest-wins` for independent read
+operations that can safely run again.
+
+## Delay rapid input calls
+
+Use `py-debounce="200"` on a read operation to wait until input stops for 200 ms.
+Each event replaces the pending call for that control. Only the final event's
+parameter snapshot is sent. Forms with `py-trigger="input"` or `change`
+serialize their named fields, as submit forms do. Input during text composition
+is not sent; the final input event supplies the completed text.
+
+```html
+<form py-call="search" py-trigger="input" py-debounce="200" py-target="#results">
+  <label for="query">Search</label>
+  <input id="query" name="query" type="search">
+</form>
+<div id="results"></div>
+```
+
+The delay defaults to zero. Clicks and submissions remain immediate unless a
+control explicitly sets `py-debounce`. A removed control cannot send its pending
+call while detached. Waiting state and request policy start when the call is
+sent, not while its timer is pending. `drop` can still reject that call if
+another operation is running; use `latest-wins` for live read results. The delay
+does not cancel Python work that has already started.
+
+## Focus after replacement
+
+Give controls stable, unique IDs. When a destructive swap removes the focused
+control, the runtime focuses the inserted control with the same ID without
+scrolling the page. Text inputs and textareas also retain their selection,
+limited to the replacement value's length.
+
+Focus is read immediately before the swap. Moving to a control outside the
+updated region during a request is respected. A lifecycle listener that sets
+focus after the swap also takes precedence. Append operations do not change
+focus. If no matching control is inserted, the runtime does not guess a new
+focus target.
+
+## Accessible loading and theme states
+
+While a request is waiting, its wait element has `aria-busy="true"` and
+`.py-waiting`. Shared wait elements remain busy until all visible waits finish
+or time out. The runtime then restores the element's original `aria-busy`
+value, or removes the attribute if it was absent. It does not add live regions
+to application content. Use `role="status"` on a short result or status message
+when an announcement is useful.
+
+Bundled themes provide readable text for each button variant, visible keyboard
+focus, and the matching light or dark color scheme for native controls.
+Reduced-motion settings remove button movement and spinner animation while
+keeping the busy marker visible. Custom theme authors should define
+`--pyh-focus`, `--pyh-color-scheme`, and the `--pyh-btn-primary-text`,
+`--pyh-btn-secondary-text`, and `--pyh-btn-danger-text` tokens along with the
+existing colors.

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

@@ -47,7 +47,9 @@ pdm add pywebview-htmx
 ## Maintainer Docs
 
 For maintainer and agent-facing repository guidance, see
-[`docs/index.md`](docs/index.md).
+[`docs/index.md`](docs/index.md). Run `pdm run check` for lint, tests, and
+offline documentation checks. The documentation check requires the native
+`perfect-doc` executable and can run alone with `pdm run check-docs`.
 
 ## Agent Skill
 
@@ -119,7 +121,7 @@ it is injected automatically.
 - 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
+- For forms with `submit`, `input`, or `change` triggers, 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.
@@ -155,6 +157,9 @@ Injects the runtime script tag into an HTML string (idempotent).
 Returns HTML-escaped JSON that is safe to place in a `data-py-params`
 attribute.
 
+Non-finite numbers (`NaN` and positive or negative infinity) raise `ValueError`.
+JSON does not support these values.
+
 ```python
 from pywebview_htmx import encode_params_attr
 
@@ -197,6 +202,9 @@ 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.
 
+A label that contains its control calls Python once per activation. Clicking
+the label text still changes the checkbox or radio state.
+
 ### `data-py-params` (optional)
 
 JSON payload passed to Python method.
@@ -207,8 +215,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
+- Invalid JSON or a value that is not an object emits `py:error`. Python is not called.
+- For forms with `submit`, `input`, or `change` triggers, named fields are serialized automatically and
   merged over this payload.
 
 ### `py-target` (optional)
@@ -248,6 +256,7 @@ Per-element concurrency override. If omitted, the global
 - `swapDelay` (ms, default: `0`)
 - `settleDelay` (ms, default: `20`)
 - `requestPolicy` (`"latest-wins"` default, or `"drop"`)
+- `requestTimeout` (ms, default: `0`; `py-timeout` overrides it per element)
 
 Runtime defaults are read for each accepted request. An element's explicit
 `py-swap` continues to override `defaultSwapStyle`; otherwise, changing
@@ -306,6 +315,9 @@ 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.
 
+The bundled loading styles show `.py-waiting` without blocking pointer input.
+The request policy controls whether another trigger is accepted.
+
 ### `latest-wins` (default)
 
 Multiple rapid requests are allowed; stale responses in the same request state
@@ -316,10 +328,33 @@ scope are ignored. Only the latest request for that scope updates the DOM.
 If a request is already in flight for the same request state scope, new triggers
 are ignored and `py:ignored` is emitted.
 
+### Python Handler Concurrency
+
+`latest-wins` does not cancel Python work. Each accepted call still runs, even
+when its returned HTML is later ignored. PyWebview runs exposed handlers in
+separate threads. Protect shared mutable data with a lock or a database
+transaction when needed.
+
+`drop` applies to the same request scope. It does not prevent calls from other
+scopes from changing the same Python data.
+
+### Bridge Readiness
+
+PyWebview creates the bridge after the document loads. Wait for the
+`pywebviewready` event before starting programmatic calls:
+
+```js
+window.addEventListener("pywebviewready", () => {
+  document.querySelector("#load-button").click();
+});
+```
+
+A call made before the bridge is available emits `py:error`. It is not queued.
+
 ## Dynamic Content Re-processing
 
-After a swap, `pywebview-htmx` automatically scans swapped content for new `py-call`
-elements and binds them. This enables chained interactions in returned fragments
+After a swap, `pywebview-htmx` binds controls in the inserted content. Append
+and outer replacement do not scan existing siblings again. This enables chained interactions in returned fragments
 without manual re-init code.
 
 ## Theme System
@@ -444,3 +479,72 @@ The demo includes:
 ## License
 
 MIT (see [LICENSE](LICENSE)).
+
+## Request deadlines
+
+Set `py-timeout="2000"` for a two-second Python response deadline. The global
+`requestTimeout` default is `0` (no deadline). Values are milliseconds from
+0 to 2147483647. A timeout emits `py:error` with `detail.phase="timeout"` and
+`error.name="TimeoutError"`. The loading indicator stops, and a late response
+cannot change the page. A late Python failure still emits `py:error` with
+`detail.expired=true`.
+
+A deadline does not cancel Python work or retry the call. Under `drop`, the
+scope stays locked until Python finishes. Show the timeout message and let the
+application check the operation's result before another attempt. If Python
+never returns, the lock remains until the page is reloaded; reloading does not
+prove that the operation was cancelled. Use `latest-wins` for independent read
+operations that can safely run again.
+
+## Delay rapid input calls
+
+Use `py-debounce="200"` on a read operation to wait until input stops for 200 ms.
+Each event replaces the pending call for that control. Only the final event's
+parameter snapshot is sent. Forms with `py-trigger="input"` or `change`
+serialize their named fields, as submit forms do. Input during text composition
+is not sent; the final input event supplies the completed text.
+
+```html
+<form py-call="search" py-trigger="input" py-debounce="200" py-target="#results">
+  <label for="query">Search</label>
+  <input id="query" name="query" type="search">
+</form>
+<div id="results"></div>
+```
+
+The delay defaults to zero. Clicks and submissions remain immediate unless a
+control explicitly sets `py-debounce`. A removed control cannot send its pending
+call while detached. Waiting state and request policy start when the call is
+sent, not while its timer is pending. `drop` can still reject that call if
+another operation is running; use `latest-wins` for live read results. The delay
+does not cancel Python work that has already started.
+
+## Focus after replacement
+
+Give controls stable, unique IDs. When a destructive swap removes the focused
+control, the runtime focuses the inserted control with the same ID without
+scrolling the page. Text inputs and textareas also retain their selection,
+limited to the replacement value's length.
+
+Focus is read immediately before the swap. Moving to a control outside the
+updated region during a request is respected. A lifecycle listener that sets
+focus after the swap also takes precedence. Append operations do not change
+focus. If no matching control is inserted, the runtime does not guess a new
+focus target.
+
+## Accessible loading and theme states
+
+While a request is waiting, its wait element has `aria-busy="true"` and
+`.py-waiting`. Shared wait elements remain busy until all visible waits finish
+or time out. The runtime then restores the element's original `aria-busy`
+value, or removes the attribute if it was absent. It does not add live regions
+to application content. Use `role="status"` on a short result or status message
+when an announcement is useful.
+
+Bundled themes provide readable text for each button variant, visible keyboard
+focus, and the matching light or dark color scheme for native controls.
+Reduced-motion settings remove button movement and spinner animation while
+keeping the busy marker visible. Custom theme authors should define
+`--pyh-focus`, `--pyh-color-scheme`, and the `--pyh-btn-primary-text`,
+`--pyh-btn-secondary-text`, and `--pyh-btn-danger-text` tokens along with the
+existing colors.

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

@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.4.1"
+version = "0.5.0"
 
 [project.license]
 file = "LICENSE"
@@ -68,6 +68,16 @@ includes = [
 ]
 
 [tool.pdm.scripts]
-test = "pytest"
+check-docs = "perfect-doc check . --offline --no-banner"
+test = "pytest --browser chromium --browser webkit"
+check-dist = "python scripts/check_distribution.py"
+test-native = "python tests/native_smoke.py"
 lint = "ruff check ."
-install-browser = "playwright install chromium"
+install-browser = "playwright install chromium webkit"
+
+[tool.pdm.scripts.check]
+composite = [
+    "lint",
+    "test",
+    "check-docs",
+]

{pywebview_htmx-0.4.1 → pywebview_htmx-0.5.0}/src/pywebview_htmx/runtime.py

@@ -2,24 +2,77 @@ from __future__ import annotations
 
 from importlib.resources import files
 import json
-import re
 from html import escape as html_escape
+from html.parser import HTMLParser
 from typing import Any
 
 import webview
 
-_SCRIPT_TAG_RE = re.compile(
-    r"<script[^>]*\bdata-pywebview-htmx\s*=\s*(?:[\"']true[\"']|true\b)",
-    re.IGNORECASE,
-)
-_THEME_TAG_RE = re.compile(
-    r"<style[^>]*\bdata-pywebview-theme\s*=\s*[\"'](?P<name>[^\"']+)[\"'][^>]*>.*?</style>",
-    re.IGNORECASE | re.DOTALL,
-)
 _THEME_BASE_NAME = "base"
 DEFAULT_THEME = "aurora"
 
 
+class _AssetTags(HTMLParser):
+    """Find active asset tags and closing tags in the original HTML."""
+
+    CDATA_CONTENT_ELEMENTS = (
+        *HTMLParser.CDATA_CONTENT_ELEMENTS, "title", "textarea", "noscript",
+    )
+
+    def __init__(self, html: str) -> None:
+        super().__init__(convert_charrefs=False)
+        self._html = html
+        self._line_starts = [0] + [
+            index + 1 for index, char in enumerate(html) if char == "\n"
+        ]
+        self._template_depth = 0
+        self._theme_start: tuple[int, str] | None = None
+        self.runtime_present = False
+        self.theme: tuple[int, int, str] | None = None
+        self.closing_tags: dict[str, int] = {}
+        self.feed(html)
+        self.close()
+
+    def _offset(self) -> int:
+        line, column = self.getpos()
+        return self._line_starts[line - 1] + column
+
+    def handle_starttag(
+        self, tag: str, attrs: list[tuple[str, str | None]],
+    ) -> None:
+        if tag == "template":
+            self._template_depth += 1
+        if self._template_depth:
+            return
+
+        attributes: dict[str, str | None] = {}
+        for name, value in attrs:
+            attributes.setdefault(name, value)
+        marker = attributes.get("data-pywebview-htmx")
+        if tag == "script" and marker is not None and marker.lower() == "true":
+            self.runtime_present = True
+        if tag == "style" and self.theme is None:
+            theme = attributes.get("data-pywebview-theme")
+            if theme is not None:
+                self._theme_start = (self._offset(), theme)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "template" and self._template_depth:
+            self._template_depth -= 1
+            return
+        if self._template_depth:
+            return
+
+        offset = self._offset()
+        if tag in {"head", "body"}:
+            self.closing_tags[tag] = offset
+        if tag == "style" and self._theme_start is not None:
+            start, theme = self._theme_start
+            end = self._html.index(">", offset) + 1
+            self.theme = (start, end, theme)
+            self._theme_start = None
+
+
 def list_themes() -> list[str]:
     """Return all bundled selectable theme names."""
     themes_dir = files("pywebview_htmx").joinpath("static/themes")
@@ -61,24 +114,21 @@ 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),
+        json.dumps(params, sort_keys=True, allow_nan=False),
         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):
+    tags = _AssetTags(html)
+    if tags.runtime_present:
         return html
 
     script_content = get_runtime_script()
     injection = f'<script data-pywebview-htmx="true">{script_content}</script>'
 
-    lower_html = html.lower()
-    body_close_idx = lower_html.rfind("</body>")
-    if body_close_idx == -1:
-        return f"{html}{injection}"
-
+    body_close_idx = tags.closing_tags.get("body", len(html))
     return f"{html[:body_close_idx]}{injection}{html[body_close_idx:]}"
 
 
@@ -88,24 +138,18 @@ def inject_theme(html: str, theme: str = DEFAULT_THEME) -> str:
     css = get_theme_css(normalized_theme)
     injection = f'<style data-pywebview-theme="{normalized_theme}">{css}</style>'
 
-    match = _THEME_TAG_RE.search(html)
-    if match:
-        current_theme = match.group("name").strip().lower()
+    tags = _AssetTags(html)
+    if tags.theme is not None:
+        start, end, current_theme = tags.theme
+        current_theme = current_theme.strip().lower()
         if current_theme == normalized_theme:
             return html
-        start, end = match.span()
         return f"{html[:start]}{injection}{html[end:]}"
 
-    lower_html = html.lower()
-    head_close_idx = lower_html.rfind("</head>")
-    if head_close_idx != -1:
-        return f"{html[:head_close_idx]}{injection}{html[head_close_idx:]}"
-
-    body_close_idx = lower_html.rfind("</body>")
-    if body_close_idx != -1:
-        return f"{html[:body_close_idx]}{injection}{html[body_close_idx:]}"
-
-    return f"{injection}{html}"
+    insertion_idx = tags.closing_tags.get(
+        "head", tags.closing_tags.get("body", 0),
+    )
+    return f"{html[:insertion_idx]}{injection}{html[insertion_idx:]}"
 
 
 def create_window(