nextpytk 0.4.1__tar.gz → 0.4.2__tar.gz

{nextpytk-0.4.1 → nextpytk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.1
+Version: 0.4.2
 Summary: Accessible, declarative Tkinter applications from ordinary Python functions.
 Project-URL: Homepage, https://github.com/nishimotz/nextpytk
 Project-URL: Repository, https://github.com/nishimotz/nextpytk
@@ -28,15 +28,21 @@ Accessible, declarative Tkinter applications from ordinary Python functions.
 
 Register widgets as plain Python functions, declare layout separately, and
 keep roles/descriptions in one place. The decorator style is Flask-inspired;
-`schema()` exports the same structure for agents and tools.
+`schema()` exports the registered widget structure as JSON-compatible data.
 Uses ttk widgets where available.
 
 ---
 
 ## Quick Start
 
+Start with an app where a button updates a message.
+
+```bash
+pip install nextpytk
+```
+
 ```python
-from nextpytk import TkApp, Layout
+from nextpytk import TkApp
 
 app = TkApp(title="Hello")
 
@@ -45,28 +51,144 @@ def msg():
     return "Hello, world!"
 
 @app.button("greet", label="Greet")
-def on_greet(values):
+def on_greet():
     return {"msg": "Button clicked!"}
 
-app.run(layout=Layout().section("msg").section("greet"))
+app.run(layout=["msg", "greet"])
 ```
 
-**Three layout styles — pick the one that fits:**
+---
+
+## How it works
+
+In nextpytk you register widgets by name and declare layout separately.
+
+This example registers two widgets: `msg` and `greet`.
+
+```python
+@app.status("msg")
+```
+
+`msg` is a status area that shows a message.
+
+```python
+@app.button("greet", label="Greet")
+```
+
+`greet` is a button labeled "Greet".
+
+Finally, name the display order:
 
 ```python
-# 1) Simple list (easiest)
 app.run(layout=["msg", "greet"])
+```
 
-# 2) Fluent DSL
-app.run(layout=Layout().section("msg").section("greet"))
+When you press the button, the callback returns this `dict`:
 
-# 3) with-block (context manager)
-with app.layout() as b:
-    b.section("msg")
-    b.section("greet")
-app.run(layout=b.build())
+```python
+{"msg": "Button clicked!"}
 ```
 
+nextpytk merges that into the app `state`.
+
+Because `msg` is the name of the registered status area, its text becomes
+"Button clicked!".
+
+So the basic flow is:
+
+* Register widgets by name
+* List those names in the layout
+* Return a `dict` from a callback
+* `state` updates and matching widgets refresh
+
+---
+
+## Using input values
+
+Next, change the app so you type a name and press Greet.
+
+```python
+from nextpytk import TkApp
+
+app = TkApp(title="Hello")
+
+@app.entry("name", placeholder="Name")
+def on_name():
+    return {}
+
+@app.status("msg")
+def msg():
+    return "Enter your name"
+
+@app.button("greet", label="Greet")
+def on_greet(values):
+    name = values["name"]
+    return {"msg": f"Hello, {name}!"}
+
+app.run(layout=["name", "greet", "msg"])
+```
+
+`entry` registers a text field.
+
+```python
+@app.entry("name", placeholder="Name")
+```
+
+Again, `"name"` is the widget name. An on-change callback is required; if you
+only read the field from a button, a no-arg callback that returns `{}` is enough.
+
+In the button callback, read the current field value from `values`:
+
+```python
+def on_greet(values):
+    name = values["name"]
+```
+
+`values["name"]` is the current value of the `entry` registered as `name`.
+
+For example, if you type
+
+```text
+Taro
+```
+
+and press the button, the callback returns:
+
+```python
+{"msg": "Hello, Taro!"}
+```
+
+That dict merges into `state` and updates the status area named `msg`.
+
+## `values` and `state`
+
+Two dictionaries appear here:
+
+* `values`
+  Input values at the moment the callback runs
+
+* `state`
+  Shared current state for the whole app
+
+A button callback reads `values`, then returns a `dict` of state changes:
+
+```python
+def on_greet(values):
+    name = values["name"]
+    return {"msg": f"Hello, {name}!"}
+```
+
+The flow is:
+
+* Type into an `entry`
+* Press the button
+* Read input from `values`
+* Return updates as a `dict`
+* Those updates merge into `state`
+* Matching widgets refresh from `state`
+
+That is nextpytk's basic state-update model.
+
 ---
 
 ## Design System
@@ -91,9 +213,80 @@ Layout().section("msg", side=Side.LEFT, fill=Fill.X)
 | `Relief` | `Relief.FLAT/RAISED/SUNKEN/...` | border style |
 | `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
 | `SelectMode` | `SelectMode.SINGLE/BROWSE/MULTIPLE/EXTENDED` | listbox mode |
+| `EventSeq` | `EventSeq.RETURN/ESCAPE/BACKSPACE/DELETE/TAB/...` | event sequences for bindings |
+| `EventSeq` (mouse) | `EventSeq.BUTTON_1/2/3`, `DOUBLE_BUTTON_1/2/3`, `PRIMARY_DOUBLE_CLICK` | mouse event sequences |
+| `EventSeq` (virtual) | `EventSeq.LISTBOX_SELECT/COMBOBOX_SELECTED/NOTEBOOK_TAB_CHANGED/...` | virtual events |
 
 Each type has a matching `*Like` literal alias (e.g. `FillLike`), so raw strings still work when needed.
 
+### Event sequences
+
+Use `EventSeq` constants for widget-level event bindings (`events=` on
+`@app.listbox` and `@app.entry`). These handlers are **separate from** the
+widget's select/change callback:
+
+| API | Handler argument | Typical use |
+|-----|------------------|-------------|
+| `@app.listbox` select callback | selected index `int` (`-1` if none) | react to selection |
+| `@app.listbox(..., events=...)` | current **state** dict | Return / double-click / Backspace |
+| `@app.entry` change callback | value `str` | react to typing |
+| `@app.entry(..., events=...)` | **entry values** dict (all entries) | Return to submit, like a button |
+
+```python
+from nextpytk.types import EventSeq, SelectMode
+
+@app.listbox(
+    "results",
+    items_key="results_items",
+    selectmode=SelectMode.BROWSE,
+    events={
+        EventSeq.RETURN: lambda state: open_child(),
+        EventSeq.PRIMARY_DOUBLE_CLICK: lambda state: open_child(),
+        EventSeq.BACKSPACE: lambda state: go_parent(),
+    },
+)
+def on_results_select(idx: int) -> dict:
+    return {"status": f"selected:{idx}"}
+
+@app.entry(
+    "query",
+    events={
+        EventSeq.RETURN: lambda values: {
+            "status": f"search:{(values.get('query') or '').strip()}"
+        },
+    },
+)
+def on_query(value: str) -> dict:
+    return {}
+```
+
+`EventSeq.PRIMARY_CLICK`, `EventSeq.PRIMARY_DOUBLE_CLICK`, and
+`EventSeq.PRIMARY_BUTTON_RELEASE` are a11y-aware lazy descriptors that
+return the event sequence for the OS-configured primary mouse button
+(accounting for left/right button swap on Windows, macOS, and Linux/GNOME).
+
+### Dynamic choices
+
+State-driven choices mirror treeview's `rows_key`: keep the selection in
+`state[name]` / `state[key]`, and refresh the options via a separate key.
+
+```python
+@app.listbox("results", items_key="results_items")
+def on_results_select(idx: int) -> dict:
+    return {}
+
+@app.combobox("folder", values_key="folder_values")
+def on_folder(value: str) -> dict:
+    return {}
+
+# Later (button, job, or initial_state):
+app.apply_state({
+    "results_items": ["a", "b", "c"],
+    "folder_values": ["INBOX", "Sent"],
+})
+```
+
+Omit `items_key` / `values_key` to keep a static `items=` / `values=` list.
 ### Spacing tokens
 
 ```python
@@ -177,6 +370,24 @@ view_layouts = {
 
 ## Layout DSL
 
+Three styles — pick the one that fits:
+
+```python
+from nextpytk import Layout
+
+# 1) Simple list (easiest)
+app.run(layout=["msg", "greet"])
+
+# 2) Fluent DSL
+app.run(layout=Layout().section("msg").section("greet"))
+
+# 3) with-block (context manager)
+with app.layout() as b:
+    b.section("msg")
+    b.section("greet")
+app.run(layout=b.build())
+```
+
 ### Simple list
 
 ```python
@@ -229,7 +440,7 @@ Grid builder methods:
 | `row_minsize(row, px)` | Row minimum height |
 | `end_grid()` | Return to Layout chain |
 
-Use `col_weight(0, 0).col_weight(1, 1)` to set column 0 → weight 0 and column 1 → weight 1. This is explicit and less error-prone than index-position bulk lists.
+Use `col_weight(0, 0).col_weight(1, 1)` to set column 0 → weight 0 and column 1 → weight 1.
 
 ### With-block (context manager)
 
@@ -271,15 +482,15 @@ app.run(layout=b.build())
 | `@app.message(name, width=..., auto_width=...)` | tk.Label (auto-wrap) | — | `str` or `dict` |
 | `@app.button(name, label=..., font=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
 | `@app.job(name)` | async callable | entry values `dict` | `dict` |
-| `@app.entry(name, placeholder=..., show=..., font=..., padding=..., width=...)` | ttk.Entry | `str` | `dict` |
+| `@app.entry(name, placeholder=..., show=..., font=..., padding=..., width=..., events=...)` | ttk.Entry | `str` | `dict` |
 | `@app.checkbutton(name, text=..., font=...)` | ttk.Checkbutton | `bool` | `dict` |
 | `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | selected value `str` | `dict` |
-| `@app.combobox(name, values=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
+| `@app.combobox(name, values=..., values_key=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
 | `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
 | `@app.text(name, width=..., height=..., font=...)` | tk.Text | full content `str` | `dict` |
 | `@app.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
 | `@app.spinbox(name, from_=..., to=..., values=..., font=...)` | ttk.Spinbox | value `str` | `dict` |
-| `@app.listbox(name, items=..., selectmode=..., font=...)` | tk.Listbox | selected item `str` | `dict` |
+| `@app.listbox(name, items=..., items_key=..., selectmode=..., font=..., events=...)` | tk.Listbox | selected index `int` (`-1` if none) | `dict` |
 | `@app.canvas(name, width=..., height=...)` | tk.Canvas | — | — |
 
 `@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
@@ -323,28 +534,33 @@ accept raw strings too.
 | `Relief` | `Relief.FLAT/RAISED/SUNKEN/GROOVE/RIDGE/SOLID` | border style |
 | `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
 | `SelectMode` | `SelectMode.SINGLE/BROWSE/MULTIPLE/EXTENDED` | listbox mode |
+| `EventSeq` | `EventSeq.RETURN/ESCAPE/BACKSPACE/DELETE/TAB/...` | event sequences for bindings |
+| `EventSeq` (mouse) | `EventSeq.BUTTON_1/2/3`, `DOUBLE_BUTTON_1/2/3`, `PRIMARY_DOUBLE_CLICK` | mouse event sequences |
+| `EventSeq` (virtual) | `EventSeq.LISTBOX_SELECT/COMBOBOX_SELECTED/NOTEBOOK_TAB_CHANGED/...` | virtual events |
 
 ---
 
-## Schema Export (Agent/LLM)
+## Schema Export
+
+`app.schema()` returns a JSON-compatible snapshot of registered widgets
+(`name`, `kind`, `label`, `role`, `description`, plus kind-specific fields).
 
 ```python
-@label("temperature")
-def t(): return "25°C"
+@app.label("temperature")
+def t():
+    return "25°C"
 
 app.schema()
 # → {"title": "...", "widgets": [{"name": "temperature", "kind": "label", ...}]}
 ```
 
-Output is JSON-compatible and can be used as a foundation for agent tools and LLM function definitions.
-
 ---
 
 ## Layout debug
 
 After widgets are built, `app.debug_layout()` returns JSON-compatible geometry
 and pack/grid info for every registered widget (useful for clipping, minsize,
-and layout regressions; also handy to hand to an agent).
+and layout regressions).
 
 ```python
 app.run(layout=["msg", "go"])  # or build via tests / custom runner