nextpytk 0.4.2__tar.gz → 0.4.4__tar.gz

{nextpytk-0.4.2 → nextpytk-0.4.4}/.gitignore

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.2
+Version: 0.4.4
 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
@@ -212,6 +212,7 @@ Layout().section("msg", side=Side.LEFT, fill=Fill.X)
 | `Orient` | `Orient.HORIZONTAL/VERTICAL` | scale / paned orientation |
 | `Relief` | `Relief.FLAT/RAISED/SUNKEN/...` | border style |
 | `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
+| `Wrap` | `Wrap.WORD/NONE/CHAR` | text wrap mode |
 | `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 |
@@ -400,6 +401,155 @@ 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 |
+| `line_numbers` | `False` | Add read-only line-number gutters to both sides |
+| `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.
+
+With `line_numbers=True` each side gains a read-only line-number gutter. Both
+panes and both gutters share a **single vertical scrollbar**, so the gutters
+stay in lock-step with the content (no drift). Logical line numbers
+(`1..n`) follow the pane content; the right pane's numbers update as you edit.
+
+
+### 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.
+
+### Dynamic region switching (swap targets)
+
+`Layout.target()` reserves a region whose contents change at runtime, mirroring
+HTMX `hx-target` / `hx-swap`. Surrounding sections (toolbar, status) stay fixed
+while only the target region swaps:
+
+```python
+layout = Layout().cluster("go_dir", "go_file", "info").target("main_area")
+
+@app.swap(
+    "main_area",
+    variants={
+        "dir":  [Layout().section("dir_tree")],
+        "file": [Layout().paired("left_text", "right_text",
+                                 fill=Fill.BOTH, expand=True)],
+    },
+    default="dir",
+)
+def main_area():
+    pass
+
+# Switch imperatively at runtime:
+app.swap_view("main_area", "file")
+```
+
+`@app.swap` variants are mounted up-front and shown/hidden via pack, so widget
+state (e.g. a treeview selection or scroll position) survives switching. Each
+variant is a `Layout` or a list of widget names. See
+`examples/swap_demo.py`.
+
 ### Fluent DSL
 
 **Pack sections:**
@@ -487,7 +637,8 @@ app.run(layout=b.build())
 | `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | 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.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=..., wrap=..., h_scroll=...)` | 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=..., items_key=..., selectmode=..., font=..., events=...)` | tk.Listbox | selected index `int` (`-1` if none) | `dict` |
@@ -495,6 +646,35 @@ app.run(layout=b.build())
 
 `@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:
@@ -509,6 +689,32 @@ Entry options: `placeholder`, `show`, `font`, `padding`, `width`, `state`.
 Button, checkbutton, radiobutton, spinbox, combobox, listbox, text options:
 - `font` is accepted uniformly. Under the hood, ttk widgets use a derived style so the rest of the theme (colors, maps, layout) is inherited.
 
+Text options (continued):
+- `wrap`: `Wrap.WORD` (default) / `Wrap.NONE` / `Wrap.CHAR`. `Wrap.NONE` keeps each logical line on a single row.
+- `h_scroll`: when `True`, a horizontal scrollbar is added (and wired to `xscrollcommand`) so long lines are reachable, typically used with `wrap=Wrap.NONE`.
+
+Every widget decorator also accepts `widget_kwargs: dict` for per-widget
+design-token overrides applied after construction. Keys are widget-native
+tk/ttk options (`padx`, `pady`, `bg`, `fg`, `font`, …). An invalid/unknown
+key is ignored rather than aborting the build:
+
+```python
+@app.text("log", wrap="none", h_scroll=True,
+          widget_kwargs={"bg": "#1e1e1e", "fg": "#dcdcdc"})
+def log(value): return {}
+```
+
+Runtime access: `app.text_widget(name)` returns the real `tk.Text`;
+`app.layout_frame(name)` returns the layout section frame that owns a
+widget (for manual grid/pack placement or re-parenting).
+`app.on_text_set(name, hook)` registers a callback to run after a text
+widget's content is replaced (used by paired line-number gutters).
+
+Enum-like options (`wrap`, `state`, `orient`, `selectmode`, `mode`) are
+validated at registration time: an invalid value raises a clear `ValueError`
+naming the option and the allowed values, instead of failing later with a
+`TclError` when the widget is built.
+
 `@app.message` creates an auto-wrapping label. `width` sets initial pixel width; `auto_width=True` (default) tracks parent container resize.
 
 ---
@@ -596,7 +802,10 @@ 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
+uv run python examples/swap_demo.py             # dynamic region switching (Layout.target + @app.swap)
 ```
 
 ---

{nextpytk-0.4.2 → nextpytk-0.4.4}/README.md

@@ -188,6 +188,7 @@ Layout().section("msg", side=Side.LEFT, fill=Fill.X)
 | `Orient` | `Orient.HORIZONTAL/VERTICAL` | scale / paned orientation |
 | `Relief` | `Relief.FLAT/RAISED/SUNKEN/...` | border style |
 | `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
+| `Wrap` | `Wrap.WORD/NONE/CHAR` | text wrap mode |
 | `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 |
@@ -376,6 +377,155 @@ 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 |
+| `line_numbers` | `False` | Add read-only line-number gutters to both sides |
+| `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.
+
+With `line_numbers=True` each side gains a read-only line-number gutter. Both
+panes and both gutters share a **single vertical scrollbar**, so the gutters
+stay in lock-step with the content (no drift). Logical line numbers
+(`1..n`) follow the pane content; the right pane's numbers update as you edit.
+
+
+### 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.
+
+### Dynamic region switching (swap targets)
+
+`Layout.target()` reserves a region whose contents change at runtime, mirroring
+HTMX `hx-target` / `hx-swap`. Surrounding sections (toolbar, status) stay fixed
+while only the target region swaps:
+
+```python
+layout = Layout().cluster("go_dir", "go_file", "info").target("main_area")
+
+@app.swap(
+    "main_area",
+    variants={
+        "dir":  [Layout().section("dir_tree")],
+        "file": [Layout().paired("left_text", "right_text",
+                                 fill=Fill.BOTH, expand=True)],
+    },
+    default="dir",
+)
+def main_area():
+    pass
+
+# Switch imperatively at runtime:
+app.swap_view("main_area", "file")
+```
+
+`@app.swap` variants are mounted up-front and shown/hidden via pack, so widget
+state (e.g. a treeview selection or scroll position) survives switching. Each
+variant is a `Layout` or a list of widget names. See
+`examples/swap_demo.py`.
+
 ### Fluent DSL
 
 **Pack sections:**
@@ -463,7 +613,8 @@ app.run(layout=b.build())
 | `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | 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.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=..., wrap=..., h_scroll=...)` | 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=..., items_key=..., selectmode=..., font=..., events=...)` | tk.Listbox | selected index `int` (`-1` if none) | `dict` |
@@ -471,6 +622,35 @@ app.run(layout=b.build())
 
 `@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:
@@ -485,6 +665,32 @@ Entry options: `placeholder`, `show`, `font`, `padding`, `width`, `state`.
 Button, checkbutton, radiobutton, spinbox, combobox, listbox, text options:
 - `font` is accepted uniformly. Under the hood, ttk widgets use a derived style so the rest of the theme (colors, maps, layout) is inherited.
 
+Text options (continued):
+- `wrap`: `Wrap.WORD` (default) / `Wrap.NONE` / `Wrap.CHAR`. `Wrap.NONE` keeps each logical line on a single row.
+- `h_scroll`: when `True`, a horizontal scrollbar is added (and wired to `xscrollcommand`) so long lines are reachable, typically used with `wrap=Wrap.NONE`.
+
+Every widget decorator also accepts `widget_kwargs: dict` for per-widget
+design-token overrides applied after construction. Keys are widget-native
+tk/ttk options (`padx`, `pady`, `bg`, `fg`, `font`, …). An invalid/unknown
+key is ignored rather than aborting the build:
+
+```python
+@app.text("log", wrap="none", h_scroll=True,
+          widget_kwargs={"bg": "#1e1e1e", "fg": "#dcdcdc"})
+def log(value): return {}
+```
+
+Runtime access: `app.text_widget(name)` returns the real `tk.Text`;
+`app.layout_frame(name)` returns the layout section frame that owns a
+widget (for manual grid/pack placement or re-parenting).
+`app.on_text_set(name, hook)` registers a callback to run after a text
+widget's content is replaced (used by paired line-number gutters).
+
+Enum-like options (`wrap`, `state`, `orient`, `selectmode`, `mode`) are
+validated at registration time: an invalid value raises a clear `ValueError`
+naming the option and the allowed values, instead of failing later with a
+`TclError` when the widget is built.
+
 `@app.message` creates an auto-wrapping label. `width` sets initial pixel width; `auto_width=True` (default) tracks parent container resize.
 
 ---
@@ -572,7 +778,10 @@ 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
+uv run python examples/swap_demo.py             # dynamic region switching (Layout.target + @app.swap)
 ```
 
 ---

{nextpytk-0.4.2 → nextpytk-0.4.4}/ROADMAP.md

@@ -130,7 +130,87 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 
 ---
 
-## Near term (post-0.4.2)
+## Snapshot (v0.4.3) — filepicker + layout blocks
+
+- Added `@app.filepicker` (`filedialog` wrapper; `mode=` open/save/directory/open_multiple).
+- Added `Layout(spacing=...)` for a layout-wide SPACE token default (padx/pady inheritance).
+- Added `Layout.frame(...)` for nested layouts (`Layout` inside `Layout`).
+- Added `Layout.cluster(...)` wrapping flow: widgets keep content/`width=` sizes and wrap left-to-right.
+- Added `Layout.paired(left, right, ..., sync_yscroll=)` for side-by-side panes with optional text y-scroll sync.
+- Docs/examples/tests for the above (`filepicker_demo`, `nested_frame_demo`, `cluster_demo`, `paired_demo`).
+
+---
+
+## Snapshot (v0.4.4) — text wrap/h-scroll, public runtime API
+
+### Text widget ergonomics (continued)
+
+- Added `wrap=` option to `@app.text` for logical-line display control:
+  - `Wrap.WORD` (default) — wrap at word boundaries.
+  - `Wrap.NONE` — keep each logical line on one row (requires horizontal scrolling).
+  - `Wrap.CHAR` — wrap at any character boundary.
+- Added a new `nextpytk.types.Wrap` typed-constant class and `WrapLike` union.
+- Added `h_scroll=` option to `@app.text`: when True, a horizontal scrollbar is added (and wired to `xscrollcommand`) so long lines are reachable in `Wrap.NONE` mode. The horizontal scrollbar is tracked in `app._text_hscrollbars`.
+
+### Decorator type-definition sync
+
+- `TreeviewOptions.double_click` is now typed and honored by `@app.treeview`.
+  - Defaults to `True`: the `activate` handler fires on double-click (previous behavior).
+  - When `False`, `activate` fires on a single `ButtonRelease-1` instead.
+- `_on_treeview_activate` accepts an optional `event` argument so the single-click binding can reuse it.
+
+### Public runtime API
+
+- Added `app.layout_frame(name)` — returns the layout frame that owns a widget (the section frame), so applications can place/re-parent widgets with grid/pack without reaching into the private `_widget_masters`.
+- This is the public replacement for the internal `_widget_masters` access that previously forced applications to depend on private state.
+
+### Per-widget design-token overrides
+
+- All widget decorators now accept `widget_kwargs: dict[str, Any]` (on `CommonWidgetOptions`).
+- Keys are widget-native tk/ttk options (`padx`, `pady`, `bg`, `fg`, `font`, …); values are the native values.
+- Overrides are applied after construction by `_apply_widget_overrides()`. An invalid/unknown key raises no error: a `TclError` is swallowed so one bad key does not abort the build.
+- This removes the need to monkey-patch the shared `tokens` module to tweak a single widget's appearance.
+
+### Decorator argument validation
+
+- Added `_validate_choice()` / `_validate_positive_int()` helpers used by the decorators to reject invalid enum-like and non-positive-int options at **registration time** (before any Tk widget is built).
+- Validated options:
+  - `text`: `state` (`normal`/`disabled`/`active`), `wrap` (`word`/`none`/`char`)
+  - `scale`, `progressbar`, `paned`: `orient` (`horizontal`/`vertical`)
+  - `listbox`, `treeview`: `selectmode` (`single`/`browse`/`multiple`/`extended`)
+  - `filepicker`: `mode` (`open`/`open_multiple`/`save`/`directory`)
+  - `progressbar`: `mode` (`determinate`/`indeterminate`)
+- A mistyped value (e.g. `wrap="wrap"`) now raises a clear `ValueError` naming the option, widget, and allowed values — instead of a cryptic `_tkinter.TclError` at runtime.
+
+### Paired line-number gutters
+
+- Added `line_numbers=True` to `Layout.paired(...)`.
+- Each side gains a read-only line-number gutter (`disabled` tk.Text, `takefocus=0`, arrow cursor).
+- **Reliable sync via a single shared vertical scrollbar**: both panes and both gutters drive one shared scrollbar. Each widget's `yscrollcommand` is chained so scrolling any widget moves the other three, and the shared scrollbar's `command` drives all four. This avoids the `yview_moveto` drift that plagued per-widget gutter chaining.
+- Gutters stay in sync when content changes via `app.text_set()` (a new `app.on_text_set()` hook) and when the editable right pane is typed into (`<KeyRelease>`).
+- Added `examples/paired_demo.py` demonstrating `line_numbers=True`.
+- The new `app.on_text_set(name, hook)` public helper lets layout features react to programmatic text replacement.
+
+### Dynamic layout switching (swap targets)
+
+- Added `Layout.target(name)` to reserve a swap region whose contents change at runtime (mirrors HTMX `hx-target`).
+- Added `@app.swap(name, variants=..., default=...)` to declare the layouts that can fill a target (mirrors HTMX `hx-swap`), and `app.swap_view(name, variant)` to switch imperatively.
+- Variants are mounted up-front and shown/hidden via `pack`/`pack_forget`, so widget state (treeview selection, scroll position) survives switching. Surrounding `Layout.section` blocks (toolbar, status) stay fixed.
+- Added `examples/swap_demo.py` (folder view <-> paired diff view).
+
+### Tests
+
+- Added `tests/test_widget_public_api.py` covering `layout_frame` and `widget_kwargs` (applied, ignored-invalid).
+- Added `tests/test_decorator_validation.py` covering invalid-option rejection for every validated widget.
+- Added wrap/h-scroll tests to `tests/test_text.py`.
+- Added `double_click` tests to `tests/test_state.py`.
+- Added paired line-number gutter tests to `tests/test_paired.py` (creation, population, shared-scrollbar sync).
+- Added swap tests to `tests/test_swap.py` (variant registration, build, switching, back-and-forth, pre-build intent).
+- Suite grew from 181 to 208 passing; pyright clean.
+
+---
+
+## Near term (post-0.4.4)
 
 ### A11y
 
@@ -147,21 +227,27 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 ### Widget expansion
 
 - [x] Per-widget `bind` for entry and listbox (`events=` on `@app.entry` and `@app.listbox`)
+- [x] Per-widget `bind` for other widgets via `widget_kwargs` / widget-level options
 - [ ] Per-widget `bind` for other widgets (`text`, `combobox`, `treeview`, `button`, etc.)
 - [x] listbox callback value design: keep selection index (unify with `treeview`)
+- [x] `@app.filepicker` — `filedialog` wrapper (schema/tool naming still open)
+- [x] Text `wrap=` / `h_scroll=` options (v0.4.4)
 
 ### Layout DSL
 
 - [x] Deprecate index-order plural methods `col_weights`/`row_weights`/`col_minsizes`/`row_minsizes` in 0.4.1 (remove in 0.5.0).
 - [ ] CSS-grid-inspired layout API for 0.5.0: explicit `grid-template-columns` / `grid-template-rows` strings (e.g. `"1fr 2fr"`, `"auto 1fr"`), area-based placement, and gap tokens. Reduce misuse by making rows/columns and widget placement visually aligned in one declaration.
-- [ ] Nested frames (`Layout` inside `Layout`)
-- [ ] Global default for `padx`/`pady`
+- [x] Nested frames (`Layout` inside `Layout`) via `Layout.frame(...)`
+- [x] Global default for `padx`/`pady` via `Layout(spacing=...)`
+- [x] `Layout.cluster(...)` wrapping flow; `Layout.paired(..., sync_yscroll=)`
+- [x] `Layout.paired(..., line_numbers=True)` read-only line-number gutters (v0.4.4)
+- [x] `Layout.target(...)` + `@app.swap(...)` dynamic region switching (v0.4.4)
 
 ### Agent / LLM integration
 
 - [ ] Expose `schema()` as Function Calling definition (bind `sequence`, treeview column defs, etc.)
 - [ ] `@agent_tool` integration (GUI operations as agent vocabulary)
-- [ ] `@app.filepicker` — `filedialog` wrapper (tool name in schema)
+- [ ] Surface `@app.filepicker` in `schema()` / tool vocabulary
 
 ---
 

{nextpytk-0.4.2 → nextpytk-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nextpytk"
-version = "0.4.2"
+version = "0.4.4"
 description = "Accessible, declarative Tkinter applications from ordinary Python functions."
 readme = "README.md"
 requires-python = ">=3.13"