zu-patterns 0.2.2__py3-none-any.whl

zu_patterns/search_box.py

@@ -0,0 +1,59 @@
+"""search_box — a lone search/textbox (label/placeholder 'search') + optional submit.
+
+Script: fill query, submit. Submitting a search is a GET ⇒ reversible-leaning.
+Success: a results-list/listbox surface appears. Failure: no surface change.
+"""
+
+from __future__ import annotations
+
+from zu_core.invariants import Invariant
+from zu_core.ports import PatternStep, RecognitionResult
+from zu_core.surface import SurfaceView
+
+from . import _match as m
+from .rail import surface_shows
+
+
+class SearchBox:
+    name = "search_box"
+    archetype = "search_box"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        box = m.first(surface, roles=("searchbox",)) or m.first(
+            surface, roles=("textbox", "combobox"), tokens=m.SEARCH_TOKENS
+        )
+        if box is None:
+            return None
+        # A dedicated searchbox role is a strong signal; a textbox merely labelled
+        # 'search' is weaker. Don't fire if it looks like a login (a password
+        # field present) — that is login_form's territory.
+        if any(m.has_state(a, "password") for a in m.of_role(surface, "textbox")):
+            return None
+        submit = m.first(surface, roles=("button",), tokens=m.SEARCH_TOKENS + ("go",))
+        confidence = 0.85 if box.role.lower() == "searchbox" else 0.62
+        script = [
+            PatternStep(op="fill", role=box.role, label_hint=m.norm(box.label), note="query")
+        ]
+        if submit is not None:
+            script.append(
+                PatternStep(
+                    op="submit", role="button", label_hint=m.norm(submit.label), note="search"
+                )
+            )
+        handles = tuple(h for h in (box.handle, submit.handle if submit else None) if h)
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=handles,
+            script=tuple(script),
+            detail="search box",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Done = a results list/listbox surface EVENTUALLY appears (by the deadline).
+        return [surface_shows(self.archetype, "results_shown", label="results", liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = an explicit "no results" empty-state appears. Safety
+        # shape: THROUGHOUT NOT contains(no results) — fires the instant it shows.
+        return [surface_shows(self.archetype, "no_results", label="no results", negate=True)]

zu_patterns/sortable_table.py

@@ -0,0 +1,59 @@
+"""sortable_table — a table/grid with column-header buttons carrying sort states.
+
+Script: click a header. Sorting is a view change ⇒ REVERSIBLE. Success: the sort
+state toggles.
+"""
+
+from __future__ import annotations
+
+from zu_core.invariants import Invariant
+from zu_core.ports import PatternStep, RecognitionResult
+from zu_core.surface import SurfaceView
+
+from . import _match as m
+from .rail import surface_shows
+
+_SORT_STATES = ("sort-asc", "sort-desc", "ascending", "descending", "sortable")
+
+
+class SortableTable:
+    name = "sortable_table"
+    archetype = "sortable_table"
+
+    def recognize(self, surface: SurfaceView) -> RecognitionResult | None:
+        has_table = bool(m.of_role(surface, "table", "grid"))
+        # A sortable header is a columnheader/button affordance with a sort state.
+        header = next(
+            (
+                a
+                for a in surface.affordances
+                if a.role.lower() in {"columnheader", "button"} and m.has_state(a, *_SORT_STATES)
+            ),
+            None,
+        )
+        if header is None:
+            return None
+        confidence = 0.8 if has_table else 0.6
+        return RecognitionResult(
+            archetype=self.archetype,
+            confidence=confidence,
+            matched_handles=(header.handle,),
+            script=(
+                PatternStep(
+                    op="click", role=header.role, label_hint=m.norm(header.label), note="sort"
+                ),
+            ),
+            detail="sortable table",
+        )
+
+    def success_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        handle = result.matched_handles[0] if result.matched_handles else None
+        # Done = the same header is EVENTUALLY present again (the table re-rendered)
+        # — a minimal liveness-by-deadline check; a richer "state toggled" check is
+        # a later predicate. Asserted as presence of the header by the deadline.
+        return [surface_shows(self.archetype, "resorted", handle=handle, liveness=True)]
+
+    def failure_invariants(self, result: RecognitionResult) -> list[Invariant]:
+        # Failure CONTEXT = an error banner appears (the re-sort errored). Safety
+        # shape: THROUGHOUT NOT contains(error) — fires the instant it lands.
+        return [surface_shows(self.archetype, "sort_error", label="error", negate=True)]

zu_patterns-0.2.2.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: zu-patterns
+Version: 0.2.2
+Summary: Zu pattern library: the policy-prior / move-ordering layer over the Action Surface (§5)
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: zu-core==0.2.9
+Description-Content-Type: text/markdown
+
+# zu-patterns — the policy-prior / move-ordering layer (§5)
+
+A UI is a state space; the **Action Surface** is the move generator (affordances
+= legal moves). This package is the **policy prior + guided search** layer over
+that surface — the *AlphaZero* shape, not Deep Blue. It does **not** brute-force a
+live space (visiting a node might charge a card). It proposes the promising
+interaction *without* exploring, and the rail (§1) verifies the prediction.
+
+## The new port — `Pattern` (group `zu.patterns`)
+
+The `Pattern` Protocol lives in **zu-core** (`zu_core.ports.Pattern`), like the
+other ports. A pattern is **read-only**: it `recognize`s a situation over a core
+`SurfaceView` (`zu_core.surface`) and emits `success_invariants` /
+`failure_invariants` (declarative `zu_core.invariants.Invariant`s the rail
+verifies). It **never** calls a tool and **never** decides the task action — that
+is the policy's job. A recognized pattern is a **prior to be confirmed by
+observation, never ground truth** (ZU-RAIL-9): its success criteria compile (via
+`compile_spec`) to Monitors, and a behaviour mismatch fires a detector.
+
+The boundary that makes this clean: `recognize` takes the **core** `SurfaceView`,
+never zu-tools' `Surface`. zu-tools projects its `Surface` onto `SurfaceView`
+through a one-way adapter (`zu_tools.surface_adapter.to_surface_view`), so
+zu-patterns depends only on zu-core.
+
+## The pieces
+
+- `recognizer.py` — a pure pass over a `SurfaceView`: classify → archetype +
+  confidence. Low confidence ⇒ **no hint** (fall through to the model).
+- `reversibility.py` — a principled, default-to-committing classifier of an
+  action as **reversible** (read-only/idempotent, safe to explore live) vs
+  **committing** (side-effecting — the live-search/rail commit boundary). No
+  site-specific keyword blocklist: HTTP-method/idempotency, affordance semantics,
+  an extensible prior set, default-to-committing on uncertainty.
+- `rail.py` — the success/failure → `Invariant` helpers shared by the patterns.
+- `search.py` — an offline best-first planner **over the Phase-1
+  `zu_core.reachability.Fsm`** with the recognizer as the move-ordering prior,
+  plus an event-log → `Fsm` transition-model builder. Pure, offline, $0. The
+  live guided-MPC loop and the Shadow-sourced transition model are **deferred
+  seams** (stubbed/documented).
+
+## The 8 starter archetypes
+
+`cookie_banner`, `login_form`, `search_box`, `modal_dialog`, `paginated_list`,
+`sortable_table`, `autocomplete`, `cart_checkout` — the last is the canonical
+**irreversible-boundary** pattern (its place-order/pay step is classified
+COMMITTING; the script stops before it).
+
+All recognition is **deterministic** structural matching over roles/labels/states
+(no model), so every pattern is tested at $0 with hand-built `SurfaceView`s. A
+small-model recognizer is a future plugin behind the same Protocol.

zu_patterns-0.2.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+zu_patterns/__init__.py,sha256=cY8Wn5TmR3gMvJ4fd7-aGqTuRKErQ-7F-vIOx_2h4pw,1141
+zu_patterns/_match.py,sha256=n_It456Ta2J6ScxZOoul_ZRGdmziClxTzE3JPQgS1SY,3100
+zu_patterns/autocomplete.py,sha256=KmbN59K2WvGyDG1RkiAVHs9bU25oiglNCHF15YVq-w4,2385
+zu_patterns/cart_checkout.py,sha256=YZRkyV7I5g22AUsGu8pfDg9mq_qaRUhG4bdAtk_21fo,4745
+zu_patterns/cookie_banner.py,sha256=PCF2QF77Z_51D6LTL5skV-qRbQvVQmzgBXSWxyOclfA,3269
+zu_patterns/login_form.py,sha256=oHIYbatH0f4PPb9aRiYjZhilZe-4REhULEw8IG-PToA,3550
+zu_patterns/modal_dialog.py,sha256=HR4TVu1yuv3dCg6euPPNg57ATHSZ72OKQ8RQ5W_GP74,3025
+zu_patterns/paginated_list.py,sha256=pDrfu9NhgnesHh2mPKebvKTxt0ZUCeaRfHs1mud005g,2191
+zu_patterns/rail.py,sha256=sprGCLvsIsufJK1supRlY-qGb1kGi7erg_7ZHE2Mrho,3853
+zu_patterns/recognizer.py,sha256=KSR0ILYiNd41BV_s3EtNG7tU41RcPx33HnJ7yR-xTUk,3272
+zu_patterns/reversibility.py,sha256=S7qIsfhO36TnNmh3GtFW8zYbkoaS4a5TvGsvb4jinUk,7076
+zu_patterns/search.py,sha256=AbSe76B5vF94F8xJ_S1g1D_UBwsjyaEvhfLGippQW6E,32174
+zu_patterns/search_box.py,sha256=NMmBdMbANLrvwHGQpNU4BHj1Sq3Xtqp-V0MaTx01jJE,2569
+zu_patterns/sortable_table.py,sha256=vPZ49LlmPGjBUEWo_sam7t8CNdiGxXBjU865UCv3HAU,2358
+zu_patterns-0.2.2.dist-info/METADATA,sha256=nJMhKDMsLto-t-1x9sgQqLOdXxuXTX7JYhqJQ8dZqjA,3699
+zu_patterns-0.2.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zu_patterns-0.2.2.dist-info/entry_points.txt,sha256=mqiuP7WrtcCysvxmohb8q6tpBewHvNruLJP2JXs4iVI,437
+zu_patterns-0.2.2.dist-info/RECORD,,

zu_patterns-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

zu_patterns-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,9 @@
+[zu.patterns]
+autocomplete = zu_patterns.autocomplete:Autocomplete
+cart_checkout = zu_patterns.cart_checkout:CartCheckout
+cookie_banner = zu_patterns.cookie_banner:CookieBanner
+login_form = zu_patterns.login_form:LoginForm
+modal_dialog = zu_patterns.modal_dialog:ModalDialog
+paginated_list = zu_patterns.paginated_list:PaginatedList
+search_box = zu_patterns.search_box:SearchBox
+sortable_table = zu_patterns.sortable_table:SortableTable