nextpytk 0.4.3__tar.gz → 0.4.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.3
+Version: 0.4.5
 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,14 +490,21 @@ 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
+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.
 
-`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.
+
+### Wrap layout
+
+`Layout.wrap()` is a wrapping flow (Flutter `Wrap` analog): 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 (`gapx`/`gapy` override it independently).
 
 ```python
 TAGS = ["python", "tkinter", "async", "uv", "type hints"]
@@ -504,13 +513,76 @@ for tag in TAGS:
     def on_tag(values, tag=tag):
         return {"msg": f"Selected: {tag}"}
 
-app.run(layout=Layout(spacing=2).status("msg").cluster(*TAGS))
+app.run(layout=Layout(spacing=2).status("msg").wrap(*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.
+Wrap is ideal for tag clouds, toolbars, and filter UIs. The layout recomputes
+rows automatically when the window is resized. Pass `gapx`/`gapy` to override
+the spacing default, and `side`/`fill`/`expand` to control how the wrap frame
+is packed.
+
+Any wrap child wrapped in `Flex(name, flex=...)` absorbs leftover horizontal
+space in its row (Flutter `Expanded` analog):
+
+```python
+from nextpytk import Flex
+
+app.run(layout=Layout().wrap("filter", Flex("search", flex=2), "ok", gapx=2))
+```
+
+For custom positioning, `Layout.flow()` takes a `FlowDelegate` (Flutter `Flow`
+analog) that computes each child's `(x, y, width, height)` from the available
+`Constraints`. See `examples/wrap_demo.py` for both `Flex` and `Flow` usage.
+
+**How it works.** `wrap` and `flow` position children with `place` (absolute
+x/y) because `pack` cannot reflow onto new rows — with `pack -side left` an
+overflowing child simply falls off the edge. `place` therefore implies a few
+constraints:
+
+- All children share one parent frame and are `place`-managed; they cannot
+  also be `pack`/`grid`-managed on the same master (mixing geometry managers
+  raises `TclError: conflicting geometry managers`).
+- Widths come from `winfo_reqwidth()`; the frame uses `pack_propagate(False)`
+  and its height is explicit.
+- On resize the flow is recomputed so rows re-wrap to the new width.
+
+Because `place` bypasses Tk's native Tab traversal (which follows pack/grid
+insertion order), `wrap` intercepts `<Tab>`/`<Shift-Tab>` and moves focus in
+the visual row-major order instead. `Entry`/`Text` children are skipped (Tab
+stays for text input); focus wraps between the first and last wrap item.
+
+> **Note:** `Layout.cluster()` was renamed to `Layout.wrap()` in 0.5.0.
+> `cluster()` remains as a deprecated alias and will be removed in 0.5.0.
+
+### 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().wrap("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
 
@@ -600,7 +672,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 +723,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.
 
 ---
@@ -710,6 +808,18 @@ print(app.debug_layout())
 # → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
 ```
 
+**Detecting geometry-manager conflicts.** Mixing `pack`/`grid`/`place` on one
+master (e.g. manually `pack`/`grid`-ing into a `place`-managed `wrap`/`flow`
+frame) cannot be fully prevented by the DSL, so `app.check_layout_conflicts()`
+inspects the widget tree and reports any such mix without waiting for a
+`TclError: conflicting geometry managers`:
+
+```python
+print(app.check_layout_conflicts())
+# → [{"master_class": "Frame", "managers": ["pack", "place"], ...}] on conflict
+#    (a warning is also emitted for each conflict)
+```
+
 ---
 
 ## Async-Native (asyncio + Tkinter)
@@ -741,6 +851,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.5}/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,14 +466,21 @@ 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
+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.
 
-`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.
+
+### Wrap layout
+
+`Layout.wrap()` is a wrapping flow (Flutter `Wrap` analog): 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 (`gapx`/`gapy` override it independently).
 
 ```python
 TAGS = ["python", "tkinter", "async", "uv", "type hints"]
@@ -480,13 +489,76 @@ for tag in TAGS:
     def on_tag(values, tag=tag):
         return {"msg": f"Selected: {tag}"}
 
-app.run(layout=Layout(spacing=2).status("msg").cluster(*TAGS))
+app.run(layout=Layout(spacing=2).status("msg").wrap(*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.
+Wrap is ideal for tag clouds, toolbars, and filter UIs. The layout recomputes
+rows automatically when the window is resized. Pass `gapx`/`gapy` to override
+the spacing default, and `side`/`fill`/`expand` to control how the wrap frame
+is packed.
+
+Any wrap child wrapped in `Flex(name, flex=...)` absorbs leftover horizontal
+space in its row (Flutter `Expanded` analog):
+
+```python
+from nextpytk import Flex
+
+app.run(layout=Layout().wrap("filter", Flex("search", flex=2), "ok", gapx=2))
+```
+
+For custom positioning, `Layout.flow()` takes a `FlowDelegate` (Flutter `Flow`
+analog) that computes each child's `(x, y, width, height)` from the available
+`Constraints`. See `examples/wrap_demo.py` for both `Flex` and `Flow` usage.
+
+**How it works.** `wrap` and `flow` position children with `place` (absolute
+x/y) because `pack` cannot reflow onto new rows — with `pack -side left` an
+overflowing child simply falls off the edge. `place` therefore implies a few
+constraints:
+
+- All children share one parent frame and are `place`-managed; they cannot
+  also be `pack`/`grid`-managed on the same master (mixing geometry managers
+  raises `TclError: conflicting geometry managers`).
+- Widths come from `winfo_reqwidth()`; the frame uses `pack_propagate(False)`
+  and its height is explicit.
+- On resize the flow is recomputed so rows re-wrap to the new width.
+
+Because `place` bypasses Tk's native Tab traversal (which follows pack/grid
+insertion order), `wrap` intercepts `<Tab>`/`<Shift-Tab>` and moves focus in
+the visual row-major order instead. `Entry`/`Text` children are skipped (Tab
+stays for text input); focus wraps between the first and last wrap item.
+
+> **Note:** `Layout.cluster()` was renamed to `Layout.wrap()` in 0.5.0.
+> `cluster()` remains as a deprecated alias and will be removed in 0.5.0.
+
+### 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().wrap("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
 
@@ -576,7 +648,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 +699,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.
 
 ---
@@ -686,6 +784,18 @@ print(app.debug_layout())
 # → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
 ```
 
+**Detecting geometry-manager conflicts.** Mixing `pack`/`grid`/`place` on one
+master (e.g. manually `pack`/`grid`-ing into a `place`-managed `wrap`/`flow`
+frame) cannot be fully prevented by the DSL, so `app.check_layout_conflicts()`
+inspects the widget tree and reports any such mix without waiting for a
+`TclError: conflicting geometry managers`:
+
+```python
+print(app.check_layout_conflicts())
+# → [{"master_class": "Frame", "managers": ["pack", "place"], ...}] on conflict
+#    (a warning is also emitted for each conflict)
+```
+
 ---
 
 ## Async-Native (asyncio + Tkinter)
@@ -717,6 +827,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.5}/ROADMAP.md

@@ -141,7 +141,119 @@ 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.
+
+---
+
+## Snapshot (v0.4.5) — Flutter-style layout vocabulary
+
+### `cluster` → `wrap` rename
+
+- `Layout.cluster()` renamed to `Layout.wrap()`, matching Flutter's `Wrap`
+  widget. `cluster()` is kept as a deprecated alias (emits a
+  `DeprecationWarning`) and will be removed in v0.5.0.
+- `LayoutBuilder.cluster()` → `LayoutBuilder.wrap()` (same alias story).
+- `examples/cluster_demo.py` → `examples/wrap_demo.py`; `tests/test_cluster.py`
+  → `tests/test_wrap.py`.
+- `gap` keyword deprecated in favor of explicit `gapx`/`gapy` (SPACE tokens).
+
+### `Flex` — absorb leftover space (Flutter `Expanded` analog)
+
+- Added `nextpytk.types.Flex(name, flex=...)`; a `wrap` child wrapped in `Flex`
+  absorbs a share of its row's leftover horizontal space proportional to its
+  flex factor, instead of keeping natural content width.
+- `widget_names()` and `mount_frames_into` resolve `Flex`-wrapped names.
+
+### `FlowDelegate` / `Layout.flow` — custom flow (Flutter `Flow` analog)
+
+- Added `nextpytk.layout.Constraints` (width/height/min/max) and
+  `nextpytk.layout.FlowDelegate` (abstract `compute_positions` /
+  `compute_height`).
+- `Layout.flow(*widgets, delegate=...)` and `LayoutBuilder.flow(...)` position
+  children via the delegate using `place`; recomputed on `<Configure>` resize.
+- `_place_flow` / `_Flow` block dispatched in `mount_frames_into` /
+  `pack_children_for`.
+- `examples/wrap_demo.py` demonstrates `wrap`, `wrap`+`Flex`, and a
+  `GridDelegate` flow.
+
+### Theme / debug
+
+- Button styles use `width=0` (cancel clam's `width=-11` min ~182px) so button
+  width tracks label text.
+- `_check_radio_padding` unified to (16,12) to match buttons;
+  `indicatormargin=(0,0,SPACE[2],0)` adds 8px between indicator and label
+  (clam ignores `indicatorpadding`).
+- `debug_layout()` detects geometry-manager conflicts;
+  `check_layout_conflicts()` warns on each.
+
+---
+
+## Near term (post-0.4.5)
 
 ### A11y
 
@@ -158,9 +270,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 +283,11 @@ 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.cluster(...)` → `Layout.wrap(...)` rename with deprecated alias (v0.4.5)
+- [x] `Flex` (Flutter `Expanded` analog) for `wrap` (v0.4.5)
+- [x] `FlowDelegate` / `Layout.flow` custom flow (Flutter `Flow` analog) (v0.4.5)
+- [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.5}/pyproject.toml

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

{nextpytk-0.4.3 → nextpytk-0.4.5}/src/nextpytk/__init__.py

@@ -3,7 +3,13 @@
 import importlib.metadata
 
 from nextpytk.app import TkApp
-from nextpytk.layout import Layout, LayoutBuilder
+from nextpytk.layout import (
+    Constraints,
+    FlowDelegate,
+    Layout,
+    LayoutBuilder,
+)
+from nextpytk.types import Flex
 from nextpytk import types
 from nextpytk.widgets import WidgetSpec
 from nextpytk.theme import (
@@ -31,6 +37,9 @@ __all__ = [
     "TkApp",
     "Layout",
     "LayoutBuilder",
+    "Constraints",
+    "FlowDelegate",
+    "Flex",
     "WidgetSpec",
     "types",
     "apply_theme",