nextpytk 0.4.1__tar.gz → 0.4.3__tar.gz

{nextpytk-0.4.1 → nextpytk-0.4.3}/.gitignore

@@ -1,4 +1,5 @@
 .venv/
 __pycache__/
 dist/
-*.egg-info/
+*.egg-info/
+.DS_Store

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.1
+Version: 0.4.3
 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"])
+```
+
+---
+
+## 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")
 ```
 
-**Three layout styles — pick the one that fits:**
+`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
@@ -189,6 +400,118 @@ Each name gets its own pack-based section. Extra kwargs forwarded to `section()`
 Layout.from_list(["a", "b"], fill="both", expand=True)
 ```
 
+### Layout spacing
+
+The default block padding comes from the design token `SPACE[1]` (4 px). Pass
+`spacing=...` to a `Layout` constructor to change the default padding for every
+block it creates:
+
+```python
+from nextpytk import tokens
+
+layout = Layout(spacing=2).section("a").section("b").grid().widget("c").end_grid()
+```
+
+`spacing` accepts a key from `nextpytk.tokens.SPACE` (1, 2, 3, 4, 6, 8). It sets
+the default `padx` and `pady` used by `section()`, `grid()`, `paned()`, grid
+`widget()` placements, and nested frames. Explicit `padx`/`pady` arguments still
+override the default.
+
+For finer control, pass `padx` or `pady` directly to the constructor:
+
+```python
+Layout(padx=tokens.SPACE[4], pady=tokens.SPACE[3]).section("a")
+```
+
+### Nested frames
+
+A `Layout` can be placed inside a named frame to group widgets visually without
+mixing pack and grid in the same parent. The inner layout owns its own spacing
+and may use any layout style (pack sections, grid, paned, or further nested
+frames).
+
+```python
+inner = Layout().section("a", "b")
+outer = Layout().section("title").frame("group", inner).section("ok")
+app.run(layout=outer)
+```
+
+`frame(name, layout, side=..., fill=..., expand=..., padx=..., pady=...)` packs
+the inner layout as a single block. The frame itself is registered under `name`,
+so it can also be placed inside a grid cell:
+
+```python
+outer = (
+    Layout()
+    .grid()
+    .widget("label")
+    .widget("group", sticky="nsew")
+    .end_grid()
+    .frame("group", Layout().section("a", "b"))
+)
+```
+
+### Paired layout
+
+`Layout.paired(left, right, ...)` places two widgets side by side in a
+single two-column frame.  It is a lighter alternative to `app.paned` for
+diff/compare views:
+
+```python
+layout = (
+    Layout()
+    .section("info")
+    .paired(
+        "left_text",
+        "right_text",
+        weight=(1, 1),
+        fill=Fill.BOTH,
+        expand=True,
+        sync_yscroll=True,
+    )
+)
+```
+
+Options:
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `weight` | `(1, 1)` | Two-column `(left, right)` grid weights |
+| `fill` | `"x"` | Frame `fill` passed to `pack` |
+| `expand` | `False` | Frame `expand` passed to `pack` |
+| `sync_yscroll` | `False` | Wire the two widgets' y-scroll commands together |
+| `side`, `padx`, `pady`, `anchor` | — | Standard `Layout` block placement options |
+
+When `sync_yscroll=True` and both widgets are `@app.text` widgets, scrolling
+either pane moves the other.  For text widgets the same effect can also be
+achieved per-widget with `@app.text(..., sync_yscroll_with="other")`; paired
+layout provides a layout-level switch that works without editing widget
+declarations.
+
+### Cluster layout
+
+`Layout.cluster()` is a wrapping flow: widgets are not stretched to fill a
+column; each keeps the width implied by its content or `width=` and they lay
+out left to right, wrapping to the next row whenever the next widget no longer
+fits in the remaining frame width. Widgets in the same row are vertically
+centered on their midline, so a tall `entry` aligns cleanly with a shorter
+`button` or `checkbutton`. The gap inherits the layout spacing by default.
+
+```python
+TAGS = ["python", "tkinter", "async", "uv", "type hints"]
+for tag in TAGS:
+    @app.button(tag, label=f"#{tag}")
+    def on_tag(values, tag=tag):
+        return {"msg": f"Selected: {tag}"}
+
+app.run(layout=Layout(spacing=2).status("msg").cluster(*TAGS))
+```
+
+Cluster is ideal for tag clouds, toolbars, and filter UIs. The layout recomputes
+rows automatically when the window is resized. Pass `gap=...` to override the
+spacing default, and `side`/`fill`/`expand` to control how the cluster frame is
+packed.
+
 ### Fluent DSL
 
 **Pack sections:**
@@ -229,7 +552,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,19 +594,49 @@ 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.filepicker(name, mode=..., label=..., title=..., filetypes=..., ...)` | ttk.Button → tkinter.filedialog | selected path(s) `str`, `list[str]`, or `None` | `dict` |
 | `@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.
 
+### File picker
+
+`@app.filepicker` creates a button that opens a tkinter file dialog.
+The selected path(s) are passed to the callback; `None` on cancel.
+
+```python
+@app.filepicker("open_file", mode="open", label="Open file",
+                title="Open file", filetypes=[("Text files", "*.txt")])
+def pick_open_file(path: str | None) -> dict[str, Any]:
+    return {"open_path": path}
+```
+
+Modes: `"open"` (default), `"open_multiple"`, `"save"`, `"directory"`.
+
+A filepicker can also be invoked from a menubar item by using its name
+as the `command`:
+
+```python
+@app.filepicker("m_open", mode="open", title="Open file")
+def m_open(path):
+    return {"open_path": path}
+
+@app.menubar("menu")
+def menu_bar():
+    return [{"label": "File", "items": [
+        {"label": "Open...", "command": "m_open"},
+    ]}]
+```
+
 `app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
 
 Common options:
@@ -323,28 +676,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
@@ -380,7 +738,9 @@ uv run python examples/widget_gallery.py      # all widget types
 uv run python examples/header_demo.py         # Layout.header / .status chrome
 uv run python examples/combobox_demo.py       # ttk.Combobox
 uv run python examples/menubar_demo.py        # menubar
+uv run python examples/filepicker_demo.py     # file picker
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
+uv run python examples/paired_demo.py           # side-by-side paired layout with y-scroll sync
 ```
 
 ---