nextpytk 0.4.3__tar.gz → 0.4.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.3
+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 |
@@ -480,6 +481,7 @@ Options:
 | `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
@@ -488,6 +490,12 @@ 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
@@ -512,6 +520,36 @@ 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:**
@@ -600,7 +638,7 @@ app.run(layout=b.build())
 | `@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.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` |
@@ -651,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.
 
 ---
@@ -741,6 +805,7 @@ 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.3 → 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 |
@@ -456,6 +457,7 @@ Options:
 | `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
@@ -464,6 +466,12 @@ 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
@@ -488,6 +496,36 @@ 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:**
@@ -576,7 +614,7 @@ app.run(layout=b.build())
 | `@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.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` |
@@ -627,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.
 
 ---
@@ -717,6 +781,7 @@ 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.3 → nextpytk-0.4.4}/ROADMAP.md

@@ -141,7 +141,76 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 
 ---
 
-## Near term (post-0.4.3)
+## 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
 
@@ -158,9 +227,11 @@ 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
 
@@ -169,6 +240,8 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 - [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
 

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

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