nextpytk 0.4.4__tar.gz → 0.4.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.4
+Version: 0.4.6
 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
@@ -496,14 +496,15 @@ 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
+### Wrap 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.
+`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"]
@@ -512,13 +513,46 @@ 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)
 
@@ -527,7 +561,7 @@ 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")
+layout = Layout().wrap("go_dir", "go_file", "info").target("main_area")
 
 @app.swap(
     "main_area",
@@ -774,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)
@@ -806,6 +852,7 @@ 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)
+uv run python examples/bottom_bar_demo.py       # pinned bottom bar (section side="bottom")
 ```
 
 ---

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

@@ -472,14 +472,15 @@ 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
+### Wrap 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.
+`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"]
@@ -488,13 +489,46 @@ 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)
 
@@ -503,7 +537,7 @@ 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")
+layout = Layout().wrap("go_dir", "go_file", "info").target("main_area")
 
 @app.swap(
     "main_area",
@@ -750,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)
@@ -782,6 +828,7 @@ 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)
+uv run python examples/bottom_bar_demo.py       # pinned bottom bar (section side="bottom")
 ```
 
 ---

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

@@ -210,7 +210,96 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 
 ---
 
-## Near term (post-0.4.4)
+## 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.
+
+---
+
+## Snapshot (v0.4.6) — section placement fix + layout ergonomics
+
+### Bug fix: `section(..., side=...)` now controls the section frame placement
+
+- `_pack_section_frame` hardcoded `side="top"`, ignoring the requested
+  placement side. A `side="bottom"` section declared after an `expand=True`
+  block (e.g. a status bar under a growing body) was pushed off-view and
+  collapsed to 1x1.
+- Fixed by honoring `block.side` on the section frame pack call.
+
+### Child packing decoupled from frame placement
+
+- Added `_Row.child_side` to separate the section frame's placement side
+  (`side`) from the side used to pack children *inside* the frame. A
+  multi-widget section still lays its children out left-to-right (`"left"`)
+  regardless of where the frame itself is placed (`side="top"`/`"bottom"`/
+  `"left"`/`"right"`); a single-widget section packs its child with the
+  frame's own placement side.
+
+### Tests / example
+
+- Added `tests/test_layout_side.py` (regression coverage: frame side
+  honored, default `top` preserved, multi-widget child `"left"` + frame
+  `"top"`/`"bottom"`).
+- Added `examples/bottom_bar_demo.py` demonstrating a `side="bottom"` bar
+  pinned below an expandable body.
+
+### Known limitation: `side="bottom"` + focusable children
+
+`side="bottom"` controls only the pack **parcel** (visual placement). Tk's
+`tk_focusNext` / `tk_focusPrev` traverse the widget tree in *insertion order*
+(`winfo children`), which is independent of the pack parcel. Because a
+`side="bottom"` section must be declared early in the tree (so an
+`expand=True` sibling doesn't push it off-view), any focusable child in it
+(Entry, Button, …) lands **early** in the Tab order even though it is
+visually at the bottom.
+
+This is fine for non-focusable chrome (labels, a `status_bar`), but **not**
+for bottom-docked interactive widgets: visual order (top → bottom controls)
+and focus order (bottom controls first) diverge. The fix is to wire the
+visual tab order explicitly (the same `_wire_tab_order` used by `wrap` /
+`flow`, which intercepts `<Key-Tab>` / `<Shift-Key-Tab>` and moves focus in
+visual row-major order). Planned to generalize for `side="bottom"` sections.
+
+---
+
+## Near term (post-0.4.5)
 
 ### A11y
 
@@ -240,6 +329,9 @@ 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)
 

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

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

{nextpytk-0.4.4 → nextpytk-0.4.6}/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",

{nextpytk-0.4.4 → nextpytk-0.4.6}/src/nextpytk/app.py

@@ -904,6 +904,7 @@ class TkApp:
             sec_id = id(master)
             if sec_id not in seen_sections:
                 seen_sections[sec_id] = {
+                    "master": master,
                     "master_class": master.winfo_class(),
                     "master_geometry": master.winfo_geometry(),
                     "widgets": [],
@@ -939,8 +940,76 @@ class TkApp:
                 pass
             seen_sections[sec_id]["widgets"].append(info)
         out["sections"] = list(seen_sections.values())
+
+        # Detect geometry-manager conflicts. Tk forbids mixing pack/grid/place
+        # on the same master; a registered widget's master may also host
+        # manual widgets (e.g. an overlay placed with ``place``), which only
+        # surface by inspecting the live child tree via ``winfo_manager``.
+        conflicts: list[dict[str, Any]] = []
+        for sec in out["sections"]:
+            master = sec.get("master")
+            managers: set[str] = set()
+            widget_names: list[str] = []
+            for w in sec["widgets"]:
+                if w["manager"]:
+                    managers.add(w["manager"])
+                widget_names.append(w["name"])
+            if master is not None:
+                try:
+                    for child in master.winfo_children():
+                        mgr = child.winfo_manager()
+                        if mgr:
+                            managers.add(mgr)
+                        label = child.cget("text") if child.winfo_class() in (
+                            "Label", "TLabel"
+                        ) else child.winfo_class()
+                        widget_names.append(label or child.winfo_name())
+                except tk.TclError:
+                    pass
+            if len(managers) > 1:
+                conflicts.append({
+                    "master_class": sec["master_class"],
+                    "managers": sorted(managers),
+                    "widgets": widget_names,
+                })
+            sec.pop("master", None)
+        out["conflicts"] = conflicts
         return out
 
+    def check_layout_conflicts(self) -> list[dict[str, Any]]:
+        """Return a list of geometry-manager conflicts, warning on each.
+
+        Tcl/Tk raises ``TclError: conflicting geometry managers`` at runtime
+        when a widget is managed by a different manager than its siblings on
+        the same master. This helper surfaces the same condition without
+        waiting for a failure: it inspects the live widget tree and reports
+        any master whose children are split across multiple managers
+        (``pack``/``grid``/``place``).
+
+        Each returned item describes one conflicting master::
+
+            {
+                "master_class": "Frame",
+                "managers": ["grid", "pack"],
+                "widgets": ["left_pane", "location"],
+            }
+
+        A ``warnings.warn`` is emitted for every conflict found, so it can be
+        used as a debugging aid after ``build_widgets`` (or inside ``run``).
+        """
+        debug = self.debug_layout()
+        conflicts: list[dict[str, Any]] = []
+        for conflict in debug.get("conflicts", []):
+            conflicts.append(conflict)
+            warnings.warn(
+                "Conflicting geometry managers on same master: "
+                f"{conflict['managers']} for widgets "
+                f"{conflict['widgets']} ({conflict['master_class']}). "
+                "Pack/grid/place cannot be mixed on one widget.",
+                stacklevel=2,
+            )
+        return conflicts
+
     def _spec(self, name: str) -> WidgetSpec | None:
         for w in self._widgets:
             if w.name == name: