nextpytk 0.4.6__tar.gz → 0.4.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.6
+Version: 0.4.8
 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
@@ -495,6 +495,11 @@ 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.
 
+> **Note:** `line_numbers=True` takes precedence over `sync_yscroll`. The
+> shared-scrollbar layout it installs keeps both panes (and both gutters)
+> scrolled in lock-step, so passing `sync_yscroll=False` together with
+> `line_numbers=True` has no effect. If the panes must scroll independently,
+> leave `line_numbers` off.
 
 ### Wrap layout
 
@@ -853,6 +858,7 @@ 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")
+uv run python examples/live_validation.py       # live validation via Tcl-var trace ingest (ingest_trace=True)
 ```
 
 ---
@@ -875,6 +881,10 @@ uv run python examples/bottom_bar_demo.py       # pinned bottom bar (section sid
 - **`CustomTkinter`**: Modern look via Canvas rendering. nextpytk takes the opposite approach: use native widgets and embed A11y from the start.
 - **`TkRouter`** (israel-dryer, author of ttkbootstrap): Declarative view routing with URL-style paths, animated transitions, and history stack. Complements nextpytk's `multiview` — routing vs widget composition.
 
+## Changelog
+
+See [CHANGES.md](./CHANGES.md) for the full release history.
+
 ## License
 
 MIT

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

@@ -471,6 +471,11 @@ 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.
 
+> **Note:** `line_numbers=True` takes precedence over `sync_yscroll`. The
+> shared-scrollbar layout it installs keeps both panes (and both gutters)
+> scrolled in lock-step, so passing `sync_yscroll=False` together with
+> `line_numbers=True` has no effect. If the panes must scroll independently,
+> leave `line_numbers` off.
 
 ### Wrap layout
 
@@ -829,6 +834,7 @@ 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")
+uv run python examples/live_validation.py       # live validation via Tcl-var trace ingest (ingest_trace=True)
 ```
 
 ---
@@ -851,6 +857,10 @@ uv run python examples/bottom_bar_demo.py       # pinned bottom bar (section sid
 - **`CustomTkinter`**: Modern look via Canvas rendering. nextpytk takes the opposite approach: use native widgets and embed A11y from the start.
 - **`TkRouter`** (israel-dryer, author of ttkbootstrap): Declarative view routing with URL-style paths, animated transitions, and history stack. Complements nextpytk's `multiview` — routing vs widget composition.
 
+## Changelog
+
+See [CHANGES.md](./CHANGES.md) for the full release history.
+
 ## License
 
 MIT

nextpytk-0.4.8/ROADMAP.md

@@ -0,0 +1,61 @@
+# ROADMAP — nextpytk
+
+> **Note:** Past release history lives in [CHANGES.md](./CHANGES.md).
+> This file is the forward-looking plan (near-term, then v0.5.0, then longer term).
+
+## Near term (post-0.4.8)
+
+### A11y
+
+- [ ] `@app.status` live-region behavior (ARIA `aria-live` equivalent / WCAG 4.1.3)
+- [ ] Tk 9.1 `tk accessible set_acc_*` real-device verification (9.1b0 + NVDA)
+- [ ] Role vocabulary mapping to Tk side
+- [ ] Automatic `emit_selection_change` (leverage `apply_state` knowing which widgets changed)
+
+### Type hints
+
+- [ ] Further TypedDict / Protocol coverage for decorator arguments
+- [ ] Fluent API equivalent to `_GridBuilder.columnconfigure`
+
+### Widget expansion
+
+- [ ] Per-widget `bind` for other widgets (`text`, `combobox`, `treeview`, `button`, etc.)
+- [ ] `@app.filepicker` — `filedialog` wrapper (schema/tool naming still open)
+
+### Layout DSL
+
+- [ ] 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.
+- [ ] Wire visual Tab order for `side="bottom"` sections via `_wire_tab_order` (see v0.4.6 note in CHANGES.md).
+
+### Agent / LLM integration
+
+- [ ] Expose `schema()` as Function Calling definition (bind `sequence`, treeview column defs, etc.)
+- [ ] `@agent_tool` integration (GUI operations as agent vocabulary)
+- [ ] Surface `@app.filepicker` in `schema()` / tool vocabulary
+
+---
+
+## v0.5.0 — themes / chrome decoupling
+
+- Remove deprecated `theme=True/False` support; `theme` becomes `str` only.
+- Remove deprecated `EventSeq.DOUBLE_CLICK`; use `EventSeq.PRIMARY_DOUBLE_CLICK` or `DOUBLE_BUTTON_1`.
+- Remove deprecated index-order plural methods `col_weights`/`row_weights`/`col_minsizes`/`row_minsizes` and `Layout.cluster()` alias.
+- Decouple `Layout().header()` / `.status()` chrome from Kizashi-specific tokens so they render safely with any ttk theme (`"none"`, `"clam"`, etc.).
+- Extract Kizashi as a standalone ttk theme package so it can be proposed upstream or reused independently of nextpytk.
+
+---
+
+## Longer term
+
+### ttk Style layer
+
+- [ ] `Layout.style("my_button", background=..., font=...)` style definitions
+
+### Declarative components
+
+- [ ] `@app.component` decorator (React-like reuse, replacing `Layout`)
+- [ ] State type definitions and validation (no Pydantic)
+
+### Testing
+
+- [ ] WidgetSpec unit tests

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

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

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

@@ -268,11 +268,17 @@ class TkApp:
         *,
         debug: bool = False,
         theme: bool | str = "kizashi",
+        ingest_trace: bool = False,
     ):
         self._title = title
         self._debug = debug
         self._theme = self._normalize_theme(theme)
         self._kizashi = self._theme == "kizashi"
+        # When True, a ``trace_add("write", ...)`` is installed on every
+        # registered Tcl variable. User edits (e.g. typing into an entry)
+        # are ingested back into ``state`` (kept as the single source of
+        # truth) and batched into a single sync pass at the next idle event.
+        self._ingest_trace = ingest_trace
         self._acc_supported: bool | None = None
         self._a11y_last_toggle: dict[str, str] = {}
         self._widgets: list[WidgetSpec] = []
@@ -280,6 +286,15 @@ class TkApp:
         self._root: tk.Tk | None = None
         self._tk_widgets: dict[str, tk.Widget] = {}
         self._tk_vars: dict[str, tk.Variable] = {}
+        # Re-entrancy guard: while the framework itself calls ``var.set``
+        # (from apply_state), a write trace must NOT re-ingest that value.
+        self._syncing_var_keys: set[str] = set()
+        # Keys whose Tcl var changed from a user edit, awaiting a batched flush.
+        self._pending_ingest: set[str] = set()
+        self._ingest_flush_job: str | None = None
+        # True while widgets are being built; build-time ``var.set`` calls
+        # (e.g. placeholders) must not be ingested into state.
+        self._building = False
         self._widget_masters: dict[str, tk.Misc] = {}
         self._row_pack_jobs: list[tuple[tk.Frame, Any]] = []
         self._grid_pack_jobs: list[tuple[tk.Frame, Any]] = []
@@ -356,7 +371,11 @@ class TkApp:
         self._text_inner.clear()
         self._text_scrollbars.clear()
         self._text_scroll_sync.clear()
+        self._text_set_hooks.clear()
         self._a11y_last_toggle.clear()
+        self._pending_ingest.clear()
+        self._ingest_flush_job = None
+        self._syncing_var_keys.clear()
         self._current_view = None
         self._current_stage = None
         self._swap_targets.clear()
@@ -1289,7 +1308,7 @@ class TkApp:
                 layout, row_jobs, grid_jobs = jobs_by_view[view]
                 layout.pack_children_for(self, row_jobs, grid_jobs)
             else:
-                self.pack_view_widgets(view, center_kinds=centered, fill="x", pady=2)
+                self.pack_view_widgets(view, center_kinds=centered, fill="x", pady=t.SPACE[1])
 
         def _on_tab_changed(_event: tk.Event[tk.Misc] | None = None) -> None:
             current = nb.select()
@@ -1461,7 +1480,7 @@ class TkApp:
                 layout, row_jobs, grid_jobs = jobs_by_stage[stage]
                 layout.pack_children_for(self, row_jobs, grid_jobs)
             else:
-                self.pack_view_widgets(stage, center_kinds=centered, fill="x", pady=2)
+                self.pack_view_widgets(stage, center_kinds=centered, fill="x", pady=t.SPACE[1])
 
         active = str(self._state.get(key, stages[0] if stages else ""))
         if active not in stages:
@@ -2608,7 +2627,7 @@ class TkApp:
         """
         width = options.get("width", 300)
         height = options.get("height", 200)
-        bg = options.get("bg", "#f0f0f0")
+        bg = options.get("bg", t.SURFACE)
         description = options.get("description")
         items = options.get("items")
         takefocus = options.get("takefocus")
@@ -2657,15 +2676,21 @@ class TkApp:
                     update_to_apply.pop(stage_key, None)
 
         self._state.update(update_to_apply)
-        for key, val in update_to_apply.items():
-            var = self._tk_vars.get(key)
-            if var is None:
-                continue
-            s = "" if val is None else str(val)
-            var.set(s)
-            w = self._tk_widgets.get(key)
-            if isinstance(w, (tk.Entry, ttk.Entry)):
-                self._apply_entry_value_after_state(key, w, var, s)
+        # Mark the keys being written by the framework so their write traces
+        # (if ingest_trace is on) do not loop the value back into state.
+        self._syncing_var_keys.update(update_to_apply)
+        try:
+            for key, val in update_to_apply.items():
+                var = self._tk_vars.get(key)
+                if var is None:
+                    continue
+                s = "" if val is None else str(val)
+                var.set(s)
+                w = self._tk_widgets.get(key)
+                if isinstance(w, (tk.Entry, ttk.Entry)):
+                    self._apply_entry_value_after_state(key, w, var, s)
+        finally:
+            self._syncing_var_keys.difference_update(update_to_apply)
         if full:
             self._sync_widgets()
         else:
@@ -2690,6 +2715,61 @@ class TkApp:
             # Keep state in sync with the rendered stage.
             self._state[key] = new_stage
 
+    def _register_var(self, key: str, var: tk.Variable) -> None:
+        """Register a Tcl variable under *key*, installing an ingest trace.
+
+        When ``ingest_trace=True``, a ``write`` trace feeds ``var.get()`` back
+        into ``state[key]`` so user edits (typing into an entry, toggling a
+        checkbutton, dragging a scale) become first-class state transitions.
+        Framework-originated writes (from ``apply_state``) are excluded via
+        ``_syncing_var_keys`` so they do not loop back. Multiple edits are
+        coalesced into one ``after_idle`` sync pass.
+        """
+        self._tk_vars[key] = var
+        if self._ingest_trace:
+            try:
+                var.trace_add(
+                    "write",
+                    lambda _n, _i, _op, k=key: self._on_var_ingest(k),
+                )
+            except tk.TclError:
+                # Variable may already be deleted; ingest is best-effort.
+                pass
+
+    def _on_var_ingest(self, key: str) -> None:
+        """Trace callback: a user edit changed ``var``; queue it for ingest."""
+        # Skip writes that the framework itself issued from apply_state, and
+        # any writes that happen while widgets are being built (placeholders).
+        if key in self._syncing_var_keys or self._building:
+            return
+        self._pending_ingest.add(key)
+        if self._root is None:
+            return
+        if self._ingest_flush_job is None:
+            try:
+                self._ingest_flush_job = self._root.after_idle(self._flush_ingest)
+            except tk.TclError:
+                self._ingest_flush_job = None
+
+    def _flush_ingest(self) -> None:
+        """Flush queued user edits into ``state`` in one batched pass."""
+        self._ingest_flush_job = None
+        if not self._pending_ingest:
+            return
+        pending = self._pending_ingest
+        self._pending_ingest = set()
+        update: dict[str, Any] = {}
+        for key in pending:
+            var = self._tk_vars.get(key)
+            if var is None:
+                continue
+            try:
+                update[key] = var.get()
+            except tk.TclError:
+                continue
+        if update:
+            self._apply_state_dict(update, full=False)
+
     def _known_state_keys(self) -> set[str]:
         """Return the set of state keys that have meaning in the app."""
         keys: set[str] = set()
@@ -3345,6 +3425,19 @@ class TkApp:
 
         self._first_focusable: tk.Widget | None = None
 
+        self._building = True
+        try:
+            self._build_widgets_inner()
+        finally:
+            self._building = False
+
+    def _build_widgets_inner(self) -> None:
+        """Create tkinter widgets from registered specs (inside build guard)."""
+        if self._root is None:
+            return
+
+        self._first_focusable: tk.Widget | None = None
+
         for spec in self._widgets:
             if spec.kind == "paned":
                 master = self._widget_masters.get(spec.name, self._root)
@@ -3745,7 +3838,7 @@ class TkApp:
             )
         w = ttk.Entry(master, textvariable=var, style=style)
         self._tk_widgets[spec.name] = w
-        self._tk_vars[spec.name] = var
+        self._register_var(spec.name, var)
         for opt in ("show", "width", "state"):
             if opt in e:
                 w.configure(**{opt: e[opt]})
@@ -3791,7 +3884,7 @@ class TkApp:
         # anchor is a ttk layout option (style.layout), not a constructor kwarg
         # for ttk.Checkbutton; left alignment is enforced by the Kizashi style.
         self._tk_widgets[spec.name] = w
-        self._tk_vars[key] = var
+        self._register_var(key, var)
         if spec.on_update is not None:
             fn = spec.on_update
             w.configure(command=lambda s=spec, f=fn, v=var, k=key:
@@ -3802,7 +3895,7 @@ class TkApp:
         gk = e.get("group_key", "radio")
         val = e.get("rb_value", "")
         if gk not in self._tk_vars:
-            self._tk_vars[gk] = tk.StringVar(value="")
+            self._register_var(gk, tk.StringVar(value=""))
         var = self._tk_vars[gk]
         # padding is owned by the theme style (44px min target size)
         style = "TRadiobutton"
@@ -3932,7 +4025,7 @@ class TkApp:
             length=e.get("length", 200 if orient_str == "horizontal" else 100),
         )  # type: ignore[arg-type]
         self._tk_widgets[spec.name] = w
-        self._tk_vars[key] = var
+        self._register_var(key, var)
         self._state[key] = str(var.get())
         if spec.on_update is not None:
             fn = spec.on_update
@@ -3963,7 +4056,7 @@ class TkApp:
             kwargs["font"] = e["font"]
         w = ttk.Spinbox(master, textvariable=var, **kwargs)
         self._tk_widgets[spec.name] = w
-        self._tk_vars[key] = var
+        self._register_var(key, var)
         if init_val:
             self._state[key] = init_val
         if spec.on_update is not None:
@@ -3989,7 +4082,7 @@ class TkApp:
             kwargs["font"] = e["font"]
         w = ttk.Combobox(master, **kwargs)
         self._tk_widgets[spec.name] = w
-        self._tk_vars[key] = var
+        self._register_var(key, var)
         if init_val:
             self._state[key] = init_val
         if spec.on_update is not None:
@@ -4000,7 +4093,7 @@ class TkApp:
     def _build_listbox(self, spec: WidgetSpec, master: tk.Misc) -> None:
         e = spec.extras
         kwargs_lb: dict[str, Any] = {
-            "bg": t.SURFACE,
+            "bg": t.BG,
             "fg": t.TEXT,
             "selectbackground": t.ACCENT_RAMP[200],
             "selectforeground": t.ACCENT_RAMP[700],

{nextpytk-0.4.6 → nextpytk-0.4.8}/src/nextpytk/layout.py

@@ -783,6 +783,25 @@ def _place_paired_with_gutters(
     _bind_gutter_edit_sync(app, text_b, gutter_b)
 
 
+def _logical_line_count(text: tk.Text) -> int:
+    """Return the number of logical (non-wrapped) lines in *text*.
+
+    ``index("end-1c")`` counts *display* lines: a long line that wraps to
+    several rows inflates the count when ``wrap`` is ``word``/``char``. We
+    count newline characters instead, which is wrap-independent. The last
+    logical line may or may not carry a trailing newline (``text_set`` omits
+    it; a hand-inserted buffer may keep it), so the count is adjusted by
+    whether the content ends with a newline.
+    """
+    try:
+        content = text.get("1.0", "end-1c")
+    except tk.TclError:
+        return 0
+    if not content:
+        return 0
+    return content.count("\n") + (0 if content.endswith("\n") else 1)
+
+
 def _reconcile_gutter(gutter: tk.Text, text: tk.Text) -> None:
     """Fill a gutter with logical line numbers, matching the text line count.
 
@@ -790,17 +809,26 @@ def _reconcile_gutter(gutter: tk.Text, text: tk.Text) -> None:
     gutter is rewritten so its scroll range matches the pane. Idempotent:
     rewriting only happens when the count differs.
     """
-    n = int(text.index("end-1c").split(".")[0])
+    # Re-entry guard: rewriting the gutter fires yscrollcommand on the shared
+    # scrollbar (via update_idletasks below), which re-enters this function
+    # through _chain_yview. Without a guard that recursion never terminates.
+    if getattr(gutter, "_syncing_gutter", False):
+        return
+    n = _logical_line_count(text)
     gutter_lines = int(gutter.index("end-1c").split(".")[0])
     if gutter_lines == n:
         return
     lines = "\n".join(str(i) for i in range(1, n + 1))
-    gutter.configure(state="normal")
-    gutter.delete("1.0", "end")
-    gutter.insert("1.0", lines)
-    gutter.configure(state="disabled")
-    # Ensure the new content is reflected in the shared scrollbar range.
-    gutter.update_idletasks()
+    gutter._syncing_gutter = True  # type: ignore[attr-defined]
+    try:
+        gutter.configure(state="normal")
+        gutter.delete("1.0", "end")
+        gutter.insert("1.0", lines)
+        gutter.configure(state="disabled")
+        # Ensure the new content is reflected in the shared scrollbar range.
+        gutter.update_idletasks()
+    finally:
+        gutter._syncing_gutter = False  # type: ignore[attr-defined]
 
 
 def _chain_yview(
@@ -857,14 +885,20 @@ def _make_gutter(parent: tk.Misc, name: str) -> tk.Text:
 
 def _populate_gutters(gutter: tk.Text, text: tk.Text) -> None:
     """Fill a gutter with logical line numbers (1..n)."""
-    n = int(text.index("end-1c").split(".")[0])
+    if getattr(gutter, "_syncing_gutter", False):
+        return
+    n = _logical_line_count(text)
     lines = "\n".join(str(i) for i in range(1, n + 1))
-    gutter.configure(state="normal")
-    gutter.delete("1.0", "end")
-    gutter.insert("1.0", lines)
-    gutter.configure(state="disabled")
-    # Ensure the new content is reflected in the shared scrollbar range.
-    gutter.update_idletasks()
+    gutter._syncing_gutter = True  # type: ignore[attr-defined]
+    try:
+        gutter.configure(state="normal")
+        gutter.delete("1.0", "end")
+        gutter.insert("1.0", lines)
+        gutter.configure(state="disabled")
+        # Ensure the new content is reflected in the shared scrollbar range.
+        gutter.update_idletasks()
+    finally:
+        gutter._syncing_gutter = False  # type: ignore[attr-defined]
 
 
 def _bind_gutter_edit_sync(app: TkApp, text: tk.Text, gutter: tk.Text) -> None:
@@ -1347,6 +1381,14 @@ class Layout:
         the gutters always stay in lock-step with the content (no drift). Line
         numbers are logical rows of the text widget (``1..n``).
 
+        .. note::
+           ``line_numbers=True`` takes precedence over ``sync_yscroll``: the
+           shared-scrollbar layout it installs always keeps the two panes (and
+           both gutters) scrolled in lock-step, so passing
+           ``sync_yscroll=False`` with ``line_numbers=True`` has no effect. If
+           you need the panes to scroll independently, do **not** enable
+           ``line_numbers``.
+
         Example::
 
             app.text("left", readonly=True, sync_yscroll_with="right")

{nextpytk-0.4.6 → nextpytk-0.4.8}/src/nextpytk/theme.py

@@ -60,7 +60,7 @@ def apply_theme(root):
     # --- entries ------------------------------------------------------------
     style.configure(
         "TEntry",
-        fieldbackground=t.SURFACE,
+        fieldbackground=t.BG,
         foreground=t.TEXT,
         bordercolor=t.DIVIDER,
         lightcolor=t.DIVIDER,
@@ -225,6 +225,11 @@ def apply_theme(root):
         font=t.font("body"),
         focuscolor=t.FOCUS,
         padding=_check_radio_padding,
+        # clam's radiobutton gap between indicator and label is driven by
+        # ``indicatormargin`` (indicatorpadding is ignored by clam). Widen the
+        # right margin to SPACE[2] (8px) to match TCheckbutton, so the symbol
+        # and label read as separate without crowding.
+        indicatormargin=(0, 0, t.SPACE[2], 0),
     )
     style.layout(
         "TRadiobutton",
@@ -252,20 +257,30 @@ def apply_theme(root):
     )
 
     # --- scale --------------------------------------------------------------
+    # "Card" thumb: page-ground (BG) fill with an ACCENT border. The border
+    # provides the non-text contrast needed to pick the thumb out of the
+    # SURFACE trough (~5.3:1, WCAG 1.4.11); the BG fill against the ACCENT
+    # border stays legible too (~5.9:1). Hover/pressed shift the border.
     style.configure(
         "TScale",
         background=t.BG,
         troughcolor=t.SURFACE,
-        bordercolor=t.DIVIDER,
-        lightcolor=t.DIVIDER,
-        darkcolor=t.DIVIDER,
+        bordercolor=t.ACCENT,
+        lightcolor=t.ACCENT,
+        darkcolor=t.ACCENT,
         padding=(t.SPACE[1], t.SPACE[2]),
     )
+    style.map(
+        "TScale",
+        bordercolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
+        lightcolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
+        darkcolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
+    )
 
     # --- spinbox ------------------------------------------------------------
     style.configure(
         "TSpinbox",
-        fieldbackground=t.SURFACE,
+        fieldbackground=t.BG,
         foreground=t.TEXT,
         bordercolor=t.DIVIDER,
         lightcolor=t.DIVIDER,
@@ -287,7 +302,7 @@ def apply_theme(root):
     # --- combobox -----------------------------------------------------------
     style.configure(
         "TCombobox",
-        fieldbackground=t.SURFACE,
+        fieldbackground=t.BG,
         foreground=t.TEXT,
         bordercolor=t.DIVIDER,
         lightcolor=t.DIVIDER,
@@ -304,7 +319,7 @@ def apply_theme(root):
         lightcolor=[("focus", t.FOCUS)],
         darkcolor=[("focus", t.FOCUS)],
         arrowcolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
-        fieldbackground=[("readonly", t.SURFACE), ("active", t.SURFACE)],
+        fieldbackground=[("readonly", t.BG), ("active", t.BG)],
         selectbackground=[("focus", t.ACCENT_RAMP[200])],
         selectforeground=[("focus", t.TEXT)],
     )
@@ -316,7 +331,7 @@ def apply_theme(root):
     # foreground so the current value stays readable.
     style.configure(
         "Readonly.TCombobox",
-        fieldbackground=t.NEUTRAL[100],
+        fieldbackground=t.BG,
         foreground=t.TEXT,
         bordercolor=t.DIVIDER,
         lightcolor=t.DIVIDER,
@@ -333,7 +348,7 @@ def apply_theme(root):
         lightcolor=[("focus", t.FOCUS)],
         darkcolor=[("focus", t.FOCUS)],
         arrowcolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
-        fieldbackground=[("readonly", t.NEUTRAL[100]), ("active", t.NEUTRAL[100])],
+        fieldbackground=[("readonly", t.BG), ("active", t.BG)],
         selectbackground=[("focus", t.ACCENT_RAMP[300])],
         selectforeground=[("focus", t.TEXT)],
         foreground=[("readonly", t.TEXT), ("active", t.TEXT)],
@@ -355,18 +370,22 @@ def apply_theme(root):
     )
 
     # --- scrollbar ----------------------------------------------------------
+    # Thumb matches the scale thumb: BG fill with an ACCENT border on a
+    # SURFACE trough. The border gives the non-text contrast to pick the
+    # thumb out of the trough; hover/pressed shift the border accent ramp.
     style.configure(
         "TScrollbar",
-        background=t.NEUTRAL[300],
+        background=t.BG,
         troughcolor=t.SURFACE,
-        bordercolor=t.DIVIDER,
+        bordercolor=t.ACCENT,
         arrowcolor=t.TEXT,
         gripcount=0,
         borderwidth=0,
     )
     style.map(
         "TScrollbar",
-        background=[("active", t.NEUTRAL[400]), ("pressed", t.NEUTRAL[500])],
+        bordercolor=[("active", t.ACCENT_HOVER), ("pressed", t.ACCENT_PRESSED)],
+        background=[("active", t.NEUTRAL[100]), ("pressed", t.NEUTRAL[200])],
         arrowcolor=[("active", t.TEXT), ("pressed", t.TEXT)],
     )
 
@@ -538,23 +557,35 @@ def field_row(parent, row, label_text, textvariable, *, label_width=None, entry_
 
 def window_header(parent, title, subtitle=None):
     """Standard top-of-window block: left-aligned title, optional muted
-    subtitle, closed by a strong 2px rule. Replaces stacks of centered
-    gray label boxes — hierarchy comes from type scale, not from boxes.
+    subtitle. Hierarchy comes from type scale and spacing, not from boxes
+    or divider lines (Kizashi design principle).
 
     Returns (title_label, subtitle_label_or_None).
     """
-    title_lbl = tk.Label(parent, text=title, bg=t.BG, fg=t.TEXT,
+    header_bg = t.BG  # "#faf8f4" — same as page background
+    
+    # Title: Kizashi h4 with space-2 (16px) internal padding for consistent
+    # background coverage. No bottom margin — spacing comes from subtitle.
+    title_lbl = tk.Label(parent, text=title, bg=header_bg, fg=t.TEXT,
                          font=t.font("h4"), anchor="w",
-                         bd=0, highlightthickness=0)
+                         bd=0, highlightthickness=0,
+                         padx=t.SPACE[2], pady=t.SPACE[2])
     title_lbl.pack(fill="x")
+    
     sub_lbl = None
     if subtitle is not None:
-        sub_lbl = tk.Label(parent, text=subtitle, bg=t.BG, fg=t.TEXT_MUTED,
+        # Kizashi small text with space-2 padding.
+        # Top margin space-2 (16px) creates the gap from title.
+        sub_lbl = tk.Label(parent, text=subtitle, bg=header_bg, fg=t.TEXT_MUTED,
                            font=t.font("small"), anchor="w",
-                           bd=0, highlightthickness=0)
-        sub_lbl.pack(fill="x", pady=(t.SPACE[1], 0))
-    rule = tk.Frame(parent, height=2, bg=t.DIVIDER, bd=0, highlightthickness=0)
-    rule.pack(fill="x", pady=(t.SPACE[3], t.SPACE[4]))
+                           bd=0, highlightthickness=0,
+                           padx=t.SPACE[2], pady=t.SPACE[2])
+        sub_lbl.pack(fill="x")
+    
+    # Add space-4 (32px) below the header to separate from the first section
+    # (Kizashi section spacing principle).
+    tk.Frame(parent, height=t.SPACE[4], bg=header_bg).pack(fill="x")
+    
     return title_lbl, sub_lbl
 
 
@@ -581,7 +612,7 @@ def data_list(parent, columns, height=12, selectmode: str = "browse"):
         else:
             tree.column(key, width=width, minwidth=width, anchor=anchor, stretch=False)
 
-    tree.tag_configure("odd", background=t.NEUTRAL[100])
+    tree.tag_configure("odd", background=t.BG)
     tree.tag_configure("even", background=t.BG)
 
     sb = ttk.Scrollbar(container, orient="vertical", command=tree.yview)
@@ -605,17 +636,16 @@ def clear_rows(tree):
 
 
 def status_bar(root, textvariable=None, text=""):
-    """Bottom status bar: a 2px rule, then a left-aligned muted line.
+    """Bottom status bar: a left-aligned muted line.
 
     Use for hints and state instead of centered label boxes.
+    Hierarchy comes from spacing and typography (Kizashi principle).
     Returns the label.
     """
     bar = tk.Frame(root, bg=t.BG, bd=0, highlightthickness=0)
     bar.pack(side="bottom", fill="x")
-    rule = tk.Frame(bar, height=2, bg=t.DIVIDER, bd=0, highlightthickness=0)
-    rule.pack(fill="x")
     lbl = tk.Label(bar, bg=t.BG, fg=t.TEXT_MUTED, font=t.font("small"),
-                   anchor="w", padx=t.SPACE[6], pady=t.SPACE[2],
+                   anchor="w", padx=t.SPACE[2], pady=t.SPACE[2],
                    bd=0, highlightthickness=0)
     if textvariable is not None:
         lbl.configure(textvariable=textvariable)

{nextpytk-0.4.6 → nextpytk-0.4.8}/src/nextpytk/tokens.py

@@ -22,7 +22,7 @@ import tkinter.font as tkfont
 # Contrast pairs are regression-tested in tests/test_tokens.py
 # (WCAG 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast).
 BG = "#faf8f4"            # Background (page ground)
-SURFACE = "#f1eae0"       # Surface (fields, panels)
+SURFACE = "#f1ece3"       # Surface (fields, panels) — Kizashi spec
 CARD = "#ffffff"          # Card background (design uses pure white on BG)
 TEXT = "#302b24"          # Text Primary
 TEXT_SECONDARY = "#4a4339"  # Paragraph text on cards/sections

nextpytk-0.4.6/ROADMAP.md

@@ -1,377 +0,0 @@
-# ROADMAP — nextpytk
-
-## Snapshot (v0.4.0)
-
-### Implemented widgets (`@app.*`)
-
-| kind | Notes |
-|------|-------|
-| `label` / `status` / `message` | Display / word-wrap. `status` sets `role=status` metadata (not a live region yet) |
-| `button` / `entry` | ttk, `state=` support |
-| `checkbutton` / `radiobutton` / `scale` / `spinbox` | ttk |
-| `combobox` | ttk.Combobox (`readonly`, `values`) |
-| `menubar` | Window menubar with cascades / `enabled_if` |
-| `text` / `listbox` / `canvas` | tk (Text: tags, readonly, paired y-scroll sync) |
-| `treeview` | Multi-column (`show="headings"`) |
-| `paned` | `ttk.Panedwindow` + `with app.pane(...)` |
-| `progressbar` | `state[key]` / `{name}_running` for determinate/indeterminate |
-| `bind` | Global shortcuts (annotates matching button) |
-
-Infrastructure: `Layout` (pack/grid, `.header()` / `.status()` chrome), `@app.multiview`, `@app.stages` / `run(stages=..., tabposition=...)`, `run` / `run_async` / `spawn` / `@app.job`, `schema()`, `debug_layout()`, builder registry, a11y choke point `_apply_a11y`.
-
-Theme: `tokens` + `apply_theme` / layout helpers (contrast + 44px target-size regressions).
-
-PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
-
-### Examples
-
-- `disk_usage_flat_async.py` — async ncdu-style viewer (`run_async` + `spawn`)
-- `combobox_demo.py`, `menubar_demo.py`, `header_demo.py`, `text_sync_demo.py`
-
----
-
-## Snapshot (v0.4.1) — post-0.4 fixes
-
-### Text widget ergonomics
-
-- `app.text_widget(name)` returns the real `tk.Text` instance (the outer container is still available via `app.widget(name)`).
-- `app.text_get(name)` returns the current full contents.
-- `text` widgets now sync from state via `apply_state({name: ...})`, including read-only panes.
-- `_on_text_change()` now reads from the real `tk.Text` instead of the empty container frame.
-- A11y traits now attach to the real `tk.Text` rather than the container frame.
-
-### Layout documentation
-
-- Horizontal splits are already supported via `app.paned(..., orient=Orient.HORIZONTAL)` and `Layout.paned(...)`; see `examples/paned_split.py` and `examples/text_sync_demo.py`.
-- `on_ready` is intended for post-build setup, not reparenting already-packed widgets. Use up-front `paned` / `grid` / `section` declarations for dynamic-looking layouts.
-- The reported layout issue was **not** a nextpytk bug: widgets were placed in row 0 but `row_weights(0, 1)` gave all vertical stretch to the empty row 1. The framework behaved as documented; the fix was on the application side to use `row_weight(0, 1)` or a `paned` layout. This motivated stronger README warnings and the deprecation of the index-order plural methods below.
-
-### Deprecations in v0.4.1 (removal in v0.5.0)
-
-- `col_weights(*weights)`, `row_weights(*weights)`, `col_minsizes(*sizes)`, and `row_minsizes(*sizes)` on `_GridBuilder` are now deprecated. They assigned weights by index position, which was easy to misuse.
-- `LayoutBuilder.grid(col_weights=..., row_weights=...)` keyword arguments are also deprecated.
-- Migrate to the explicit singular API: `col_weight(col, weight)`, `row_weight(row, weight)`, `col_minsize(col, size)`, `row_minsize(row, size)`.
-
-### Design system documentation (v0.4.1)
-
-- Added a "Design System" section to README covering `Fill`/`Sticky`/`Orient` typed constants, `SPACE` token usage, and theme helpers.
-- Documented the `SPACE` scale (`1:4, 2:8, 3:12, 4:16, 6:24, 8:32`) and the rule of using tokens instead of bare integers for padding/spacing.
-- Updated `examples/grid_temp.py` and `examples/widget_gallery.py` to use the singular weight/min size API and `SPACE` tokens.
-
-### Widget-level font and padding (v0.4.1)
-
-- Added `font=` to `@app.button`, `@app.entry`, `@app.checkbutton`, `@app.radiobutton`, `@app.text`, `@app.spinbox`, `@app.listbox`, and `@app.combobox` (in addition to the existing `@app.label`).
-- Added `padding=` to `@app.entry` so users can declaratively increase visual height (`ttk.Entry` does not expose `height` directly).
-- For ttk widgets whose widget-level `configure()` rejects `-font` / `-padding` (Button, Entry, Checkbutton, Radiobutton), nextpytk now creates a derived `ttk.Style` per widget. The new style inherits the base style's layout and theme, applies only the requested overrides, and leaves other theme properties intact.
-- Updated README.md, README.ja.md, and `tests/test_api.py` to cover the new options.
-
-### Theme API redesign (v0.4.1)
-
-- `TkApp(theme=...)` now accepts `bool | str`.
-  - `"kizashi"` (default) applies the built-in Kizashi design system.
-  - `"none"` leaves the platform default ttk theme untouched.
-  - Any other string switches to that installed ttk theme without Kizashi overrides.
-- `theme=True` and `theme=False` are deprecated in v0.4.1 and will be removed in v0.5.0. Migrate to `"kizashi"` and `"none"`.
-- Updated `README.md`, `README.ja.md`, and `tests/test_api.py`.
-
-### Deferred
-
-- `listbox` callback stays index-based by design (unifies with `treeview`, handles duplicate items, and avoids forcing the framework to reverse-map strings). Passing the display string would be a breaking change and is intentionally not pursued.
-
----
-
-## Snapshot (v0.4.2) — event-sequence generalization + listbox items_key
-
-### Problem
-
-`@app.bind(...)` accepts arbitrary Tk event strings, but the only typed constants lived under `nextpytk.types.ListboxEvent` (e.g. `ListboxEvent.RETURN`). Using a listbox-oriented name for a global shortcut or an entry-level Enter binding was confusing.
-
-### Change
-
-- Added a generic `nextpytk.types.EventSeq` class with common event sequences: `RETURN`, `ESCAPE`, `BACKSPACE`, `DELETE`, `TAB`, `DOUBLE_BUTTON_1`, `DOUBLE_BUTTON_2`, `DOUBLE_BUTTON_3`, `LISTBOX_SELECT`.
-- Kept `ListboxEvent` as a backward-compatible subclass of `EventSeq` so existing code continues to work. Existing constants (`SELECT`, `RETURN`, `KEY_BACKSPACE`, `KEY_DELETE`) still resolve to the same string values. `DOUBLE_CLICK` is kept as a deprecated alias of `DOUBLE_BUTTON_1` and will be removed in v0.5.0.
-- Updated `EventSeqLike` / `ListboxEventLike` to share the same literal union.
-- Updated `app.py` docstrings for `@app.bind` and `@app.listbox` to reference `EventSeq` instead of `ListboxEvent`.
-
-### listbox / combobox dynamic choices
-
-- Added `items_key=` option to `@app.listbox` for state-driven list contents, symmetric to `treeview`'s existing `rows_key=`.
-- Added `values_key=` option to `@app.combobox` for state-driven dropdown values, following the same widget-native naming principle.
-- With these keys, `apply_state({items_key: [...]})` / `apply_state({values_key: [...]})` refresh the widget choices while keeping the selection in `state[name]` / `state[key]`.
-- Static `items=` / `values=` remain available and still work as before. When both are provided, the dynamic key takes precedence at runtime.
-- Full (`apply_state`) and partial (`_apply_state_dict`) updates both refresh the affected widgets when the dynamic key is touched.
-- Selection is kept when it remains valid; if it becomes invalid (removed from values, out of range for listbox) it is reset to the widget's empty state.
-
-### entry widget-level events
-
-- Added `events=` option to `@app.entry` for widget-level event bindings.
-- Accepts `dict[str, ListboxEventHandler]` mapping event sequences (e.g. `EventSeq.RETURN`) to handlers.
-- Handlers receive a dict of current effective entry values (same shape as button callbacks) and may return a state update dict.
-- Enables patterns like "press Enter in the search entry to trigger search" without a global `<Return>` bind or an application-level button.
-
-### A11y-aware primary mouse-button helpers
-
-- Added `EventSeq.PRIMARY_CLICK`, `EventSeq.PRIMARY_DOUBLE_CLICK`, and `EventSeq.PRIMARY_BUTTON_RELEASE` lazy descriptors to `nextpytk.types`. These return the tkinter event sequence for the OS-configured primary mouse button, accounting for left/right button swap on Windows, macOS, and Linux/GNOME. (The underlying `primary_click()`, `primary_double_click()`, and `primary_button_release()` functions are also available for direct use.)
-- `_primary_button_number()` detects the swap setting per platform and caches the result with `functools.lru_cache(maxsize=1)` so repeated event lookups do not hit the OS each time.
-- `EventSeq.PRIMARY_CLICK`, `EventSeq.PRIMARY_DOUBLE_CLICK`, and `EventSeq.PRIMARY_BUTTON_RELEASE` are lazy descriptors that re-evaluate on each access (the underlying `_primary_button_number()` is cached, so the cost is negligible). These are the recommended way to reference primary-button events in widget-level bindings (e.g. `events={EventSeq.PRIMARY_DOUBLE_CLICK: ...}` on `@app.listbox`).
-- Updated `examples/disk_usage_flat_async.py` and the `@app.listbox` docstring to use `EventSeq.PRIMARY_DOUBLE_CLICK` instead of the deprecated `EventSeq.DOUBLE_CLICK`.
-
-### Tests
-
-- Added `tests/test_types.py` covering `DOUBLE_BUTTON_*`, the `DOUBLE_CLICK` alias, default primary-button behavior, and mocked Windows/macOS/GNOME left-handed settings returning the swapped button number.
-
-### Design principle
-
-- Use the tkinter-native vocabulary per widget: listbox has "items", treeview has "rows", combobox has "values". The corresponding dynamic keys are `items_key`, `rows_key`, and `values_key`. This is more intuitive than forcing a single generic name across widgets.
-
-### Deprecation note
-
-- `ListboxEvent` is soft-deprecated in v0.4.2. New code should use `EventSeq` directly. No removal timeline yet.
-
----
-
-## 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.
-
----
-
-## 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
-
-- [ ] `@app.status` live-region behavior (ARIA `aria-live` equivalent / WCAG 4.1.3)
-- [ ] Tk 9.1 `tk accessible set_acc_*` real-device verification (9.1b0 + NVDA)
-- [ ] Role vocabulary mapping to Tk side
-- [ ] Automatic `emit_selection_change` (leverage `apply_state` knowing which widgets changed)
-
-### Type hints
-
-- [ ] Further TypedDict / Protocol coverage for decorator arguments
-- [ ] Fluent API equivalent to `_GridBuilder.columnconfigure`
-
-### 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.
-- [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
-
-- [ ] Expose `schema()` as Function Calling definition (bind `sequence`, treeview column defs, etc.)
-- [ ] `@agent_tool` integration (GUI operations as agent vocabulary)
-- [ ] Surface `@app.filepicker` in `schema()` / tool vocabulary
-
----
-
-### v0.5.0 themes / chrome decoupling
-
-- Remove deprecated `theme=True/False` support; `theme` becomes `str` only.
-- Remove deprecated `EventSeq.DOUBLE_CLICK`; use `EventSeq.PRIMARY_DOUBLE_CLICK` or `DOUBLE_BUTTON_1`.
-- Decouple `Layout().header()` / `.status()` chrome from Kizashi-specific tokens so they render safely with any ttk theme (`"none"`, `"clam"`, etc.).
-- Extract Kizashi as a standalone ttk theme package so it can be proposed upstream or reused independently of nextpytk.
-
-### Longer term
-
-### ttk Style layer
-
-- [x] Theme switching (`ttk.Style().theme_use(...)`)
-- [ ] `Layout.style("my_button", background=..., font=...)` style definitions
-
-### Declarative components
-
-- [ ] `@app.component` decorator (React-like reuse, replacing `Layout`)
-- [ ] State type definitions and validation (no Pydantic)
-
-### Testing
-
-- [x] Headless execution tests (`tests/` — withdrawn root, build/apply_state/callback drive)
-- [ ] WidgetSpec unit tests
-
----
-
-## Earlier snapshots
-
-### v0.3.0
-
-Builder registry, headless tests, a11y wiring (`_apply_a11y`), error policy, bugfixes.
-`run_async` / `spawn` / `@app.job`, public runtime API (`build_widgets`, `apply_state`, `register_widget_builder`, …).