nextpytk 0.4.2__tar.gz → 0.4.3__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextpytk
-Version: 0.4.2
+Version: 0.4.3
 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
@@ -400,6 +400,118 @@ Each name gets its own pack-based section. Extra kwargs forwarded to `section()`
 Layout.from_list(["a", "b"], fill="both", expand=True)
 ```
 
+### Layout spacing
+
+The default block padding comes from the design token `SPACE[1]` (4 px). Pass
+`spacing=...` to a `Layout` constructor to change the default padding for every
+block it creates:
+
+```python
+from nextpytk import tokens
+
+layout = Layout(spacing=2).section("a").section("b").grid().widget("c").end_grid()
+```
+
+`spacing` accepts a key from `nextpytk.tokens.SPACE` (1, 2, 3, 4, 6, 8). It sets
+the default `padx` and `pady` used by `section()`, `grid()`, `paned()`, grid
+`widget()` placements, and nested frames. Explicit `padx`/`pady` arguments still
+override the default.
+
+For finer control, pass `padx` or `pady` directly to the constructor:
+
+```python
+Layout(padx=tokens.SPACE[4], pady=tokens.SPACE[3]).section("a")
+```
+
+### Nested frames
+
+A `Layout` can be placed inside a named frame to group widgets visually without
+mixing pack and grid in the same parent. The inner layout owns its own spacing
+and may use any layout style (pack sections, grid, paned, or further nested
+frames).
+
+```python
+inner = Layout().section("a", "b")
+outer = Layout().section("title").frame("group", inner).section("ok")
+app.run(layout=outer)
+```
+
+`frame(name, layout, side=..., fill=..., expand=..., padx=..., pady=...)` packs
+the inner layout as a single block. The frame itself is registered under `name`,
+so it can also be placed inside a grid cell:
+
+```python
+outer = (
+    Layout()
+    .grid()
+    .widget("label")
+    .widget("group", sticky="nsew")
+    .end_grid()
+    .frame("group", Layout().section("a", "b"))
+)
+```
+
+### Paired layout
+
+`Layout.paired(left, right, ...)` places two widgets side by side in a
+single two-column frame.  It is a lighter alternative to `app.paned` for
+diff/compare views:
+
+```python
+layout = (
+    Layout()
+    .section("info")
+    .paired(
+        "left_text",
+        "right_text",
+        weight=(1, 1),
+        fill=Fill.BOTH,
+        expand=True,
+        sync_yscroll=True,
+    )
+)
+```
+
+Options:
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `weight` | `(1, 1)` | Two-column `(left, right)` grid weights |
+| `fill` | `"x"` | Frame `fill` passed to `pack` |
+| `expand` | `False` | Frame `expand` passed to `pack` |
+| `sync_yscroll` | `False` | Wire the two widgets' y-scroll commands together |
+| `side`, `padx`, `pady`, `anchor` | — | Standard `Layout` block placement options |
+
+When `sync_yscroll=True` and both widgets are `@app.text` widgets, scrolling
+either pane moves the other.  For text widgets the same effect can also be
+achieved per-widget with `@app.text(..., sync_yscroll_with="other")`; paired
+layout provides a layout-level switch that works without editing widget
+declarations.
+
+### Cluster layout
+
+`Layout.cluster()` is a wrapping flow: widgets are not stretched to fill a
+column; each keeps the width implied by its content or `width=` and they lay
+out left to right, wrapping to the next row whenever the next widget no longer
+fits in the remaining frame width. Widgets in the same row are vertically
+centered on their midline, so a tall `entry` aligns cleanly with a shorter
+`button` or `checkbutton`. The gap inherits the layout spacing by default.
+
+```python
+TAGS = ["python", "tkinter", "async", "uv", "type hints"]
+for tag in TAGS:
+    @app.button(tag, label=f"#{tag}")
+    def on_tag(values, tag=tag):
+        return {"msg": f"Selected: {tag}"}
+
+app.run(layout=Layout(spacing=2).status("msg").cluster(*TAGS))
+```
+
+Cluster is ideal for tag clouds, toolbars, and filter UIs. The layout recomputes
+rows automatically when the window is resized. Pass `gap=...` to override the
+spacing default, and `side`/`fill`/`expand` to control how the cluster frame is
+packed.
+
 ### Fluent DSL
 
 **Pack sections:**
@@ -487,6 +599,7 @@ app.run(layout=b.build())
 | `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | selected value `str` | `dict` |
 | `@app.combobox(name, values=..., values_key=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
 | `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
+| `@app.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.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
 | `@app.spinbox(name, from_=..., to=..., values=..., font=...)` | ttk.Spinbox | value `str` | `dict` |
@@ -495,6 +608,35 @@ app.run(layout=b.build())
 
 `@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
 
+### File picker
+
+`@app.filepicker` creates a button that opens a tkinter file dialog.
+The selected path(s) are passed to the callback; `None` on cancel.
+
+```python
+@app.filepicker("open_file", mode="open", label="Open file",
+                title="Open file", filetypes=[("Text files", "*.txt")])
+def pick_open_file(path: str | None) -> dict[str, Any]:
+    return {"open_path": path}
+```
+
+Modes: `"open"` (default), `"open_multiple"`, `"save"`, `"directory"`.
+
+A filepicker can also be invoked from a menubar item by using its name
+as the `command`:
+
+```python
+@app.filepicker("m_open", mode="open", title="Open file")
+def m_open(path):
+    return {"open_path": path}
+
+@app.menubar("menu")
+def menu_bar():
+    return [{"label": "File", "items": [
+        {"label": "Open...", "command": "m_open"},
+    ]}]
+```
+
 `app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
 
 Common options:
@@ -596,7 +738,9 @@ uv run python examples/widget_gallery.py      # all widget types
 uv run python examples/header_demo.py         # Layout.header / .status chrome
 uv run python examples/combobox_demo.py       # ttk.Combobox
 uv run python examples/menubar_demo.py        # menubar
+uv run python examples/filepicker_demo.py     # file picker
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
+uv run python examples/paired_demo.py           # side-by-side paired layout with y-scroll sync
 ```
 
 ---

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

@@ -376,6 +376,118 @@ Each name gets its own pack-based section. Extra kwargs forwarded to `section()`
 Layout.from_list(["a", "b"], fill="both", expand=True)
 ```
 
+### Layout spacing
+
+The default block padding comes from the design token `SPACE[1]` (4 px). Pass
+`spacing=...` to a `Layout` constructor to change the default padding for every
+block it creates:
+
+```python
+from nextpytk import tokens
+
+layout = Layout(spacing=2).section("a").section("b").grid().widget("c").end_grid()
+```
+
+`spacing` accepts a key from `nextpytk.tokens.SPACE` (1, 2, 3, 4, 6, 8). It sets
+the default `padx` and `pady` used by `section()`, `grid()`, `paned()`, grid
+`widget()` placements, and nested frames. Explicit `padx`/`pady` arguments still
+override the default.
+
+For finer control, pass `padx` or `pady` directly to the constructor:
+
+```python
+Layout(padx=tokens.SPACE[4], pady=tokens.SPACE[3]).section("a")
+```
+
+### Nested frames
+
+A `Layout` can be placed inside a named frame to group widgets visually without
+mixing pack and grid in the same parent. The inner layout owns its own spacing
+and may use any layout style (pack sections, grid, paned, or further nested
+frames).
+
+```python
+inner = Layout().section("a", "b")
+outer = Layout().section("title").frame("group", inner).section("ok")
+app.run(layout=outer)
+```
+
+`frame(name, layout, side=..., fill=..., expand=..., padx=..., pady=...)` packs
+the inner layout as a single block. The frame itself is registered under `name`,
+so it can also be placed inside a grid cell:
+
+```python
+outer = (
+    Layout()
+    .grid()
+    .widget("label")
+    .widget("group", sticky="nsew")
+    .end_grid()
+    .frame("group", Layout().section("a", "b"))
+)
+```
+
+### Paired layout
+
+`Layout.paired(left, right, ...)` places two widgets side by side in a
+single two-column frame.  It is a lighter alternative to `app.paned` for
+diff/compare views:
+
+```python
+layout = (
+    Layout()
+    .section("info")
+    .paired(
+        "left_text",
+        "right_text",
+        weight=(1, 1),
+        fill=Fill.BOTH,
+        expand=True,
+        sync_yscroll=True,
+    )
+)
+```
+
+Options:
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `weight` | `(1, 1)` | Two-column `(left, right)` grid weights |
+| `fill` | `"x"` | Frame `fill` passed to `pack` |
+| `expand` | `False` | Frame `expand` passed to `pack` |
+| `sync_yscroll` | `False` | Wire the two widgets' y-scroll commands together |
+| `side`, `padx`, `pady`, `anchor` | — | Standard `Layout` block placement options |
+
+When `sync_yscroll=True` and both widgets are `@app.text` widgets, scrolling
+either pane moves the other.  For text widgets the same effect can also be
+achieved per-widget with `@app.text(..., sync_yscroll_with="other")`; paired
+layout provides a layout-level switch that works without editing widget
+declarations.
+
+### Cluster layout
+
+`Layout.cluster()` is a wrapping flow: widgets are not stretched to fill a
+column; each keeps the width implied by its content or `width=` and they lay
+out left to right, wrapping to the next row whenever the next widget no longer
+fits in the remaining frame width. Widgets in the same row are vertically
+centered on their midline, so a tall `entry` aligns cleanly with a shorter
+`button` or `checkbutton`. The gap inherits the layout spacing by default.
+
+```python
+TAGS = ["python", "tkinter", "async", "uv", "type hints"]
+for tag in TAGS:
+    @app.button(tag, label=f"#{tag}")
+    def on_tag(values, tag=tag):
+        return {"msg": f"Selected: {tag}"}
+
+app.run(layout=Layout(spacing=2).status("msg").cluster(*TAGS))
+```
+
+Cluster is ideal for tag clouds, toolbars, and filter UIs. The layout recomputes
+rows automatically when the window is resized. Pass `gap=...` to override the
+spacing default, and `side`/`fill`/`expand` to control how the cluster frame is
+packed.
+
 ### Fluent DSL
 
 **Pack sections:**
@@ -463,6 +575,7 @@ app.run(layout=b.build())
 | `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | selected value `str` | `dict` |
 | `@app.combobox(name, values=..., values_key=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
 | `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
+| `@app.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.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
 | `@app.spinbox(name, from_=..., to=..., values=..., font=...)` | ttk.Spinbox | value `str` | `dict` |
@@ -471,6 +584,35 @@ app.run(layout=b.build())
 
 `@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
 
+### File picker
+
+`@app.filepicker` creates a button that opens a tkinter file dialog.
+The selected path(s) are passed to the callback; `None` on cancel.
+
+```python
+@app.filepicker("open_file", mode="open", label="Open file",
+                title="Open file", filetypes=[("Text files", "*.txt")])
+def pick_open_file(path: str | None) -> dict[str, Any]:
+    return {"open_path": path}
+```
+
+Modes: `"open"` (default), `"open_multiple"`, `"save"`, `"directory"`.
+
+A filepicker can also be invoked from a menubar item by using its name
+as the `command`:
+
+```python
+@app.filepicker("m_open", mode="open", title="Open file")
+def m_open(path):
+    return {"open_path": path}
+
+@app.menubar("menu")
+def menu_bar():
+    return [{"label": "File", "items": [
+        {"label": "Open...", "command": "m_open"},
+    ]}]
+```
+
 `app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
 
 Common options:
@@ -572,7 +714,9 @@ uv run python examples/widget_gallery.py      # all widget types
 uv run python examples/header_demo.py         # Layout.header / .status chrome
 uv run python examples/combobox_demo.py       # ttk.Combobox
 uv run python examples/menubar_demo.py        # menubar
+uv run python examples/filepicker_demo.py     # file picker
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
+uv run python examples/paired_demo.py           # side-by-side paired layout with y-scroll sync
 ```
 
 ---

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

@@ -130,7 +130,18 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 
 ---
 
-## Near term (post-0.4.2)
+## Snapshot (v0.4.3) — filepicker + layout blocks
+
+- Added `@app.filepicker` (`filedialog` wrapper; `mode=` open/save/directory/open_multiple).
+- Added `Layout(spacing=...)` for a layout-wide SPACE token default (padx/pady inheritance).
+- Added `Layout.frame(...)` for nested layouts (`Layout` inside `Layout`).
+- Added `Layout.cluster(...)` wrapping flow: widgets keep content/`width=` sizes and wrap left-to-right.
+- Added `Layout.paired(left, right, ..., sync_yscroll=)` for side-by-side panes with optional text y-scroll sync.
+- Docs/examples/tests for the above (`filepicker_demo`, `nested_frame_demo`, `cluster_demo`, `paired_demo`).
+
+---
+
+## Near term (post-0.4.3)
 
 ### A11y
 
@@ -149,19 +160,21 @@ PyPI: Trusted Publishing on `v*` tag push (`.github/workflows/publish.yml`).
 - [x] Per-widget `bind` for entry and listbox (`events=` on `@app.entry` and `@app.listbox`)
 - [ ] 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)
 
 ### Layout DSL
 
 - [x] Deprecate index-order plural methods `col_weights`/`row_weights`/`col_minsizes`/`row_minsizes` in 0.4.1 (remove in 0.5.0).
 - [ ] CSS-grid-inspired layout API for 0.5.0: explicit `grid-template-columns` / `grid-template-rows` strings (e.g. `"1fr 2fr"`, `"auto 1fr"`), area-based placement, and gap tokens. Reduce misuse by making rows/columns and widget placement visually aligned in one declaration.
-- [ ] Nested frames (`Layout` inside `Layout`)
-- [ ] Global default for `padx`/`pady`
+- [x] Nested frames (`Layout` inside `Layout`) via `Layout.frame(...)`
+- [x] Global default for `padx`/`pady` via `Layout(spacing=...)`
+- [x] `Layout.cluster(...)` wrapping flow; `Layout.paired(..., sync_yscroll=)`
 
 ### Agent / LLM integration
 
 - [ ] Expose `schema()` as Function Calling definition (bind `sequence`, treeview column defs, etc.)
 - [ ] `@agent_tool` integration (GUI operations as agent vocabulary)
-- [ ] `@app.filepicker` — `filedialog` wrapper (tool name in schema)
+- [ ] Surface `@app.filepicker` in `schema()` / tool vocabulary
 
 ---
 

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

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

{nextpytk-0.4.2 → nextpytk-0.4.3}/src/nextpytk/app.py

@@ -37,6 +37,8 @@ from nextpytk.types import (
     ComboboxOptions,
     EntryOptions,
     EventSeq,
+    FilepickerCallback,
+    FilepickerOptions,
     FillLike,
     LabelOptions,
     EntryEventHandler,
@@ -103,6 +105,9 @@ ButtonCallback = (
 )
 BindCallback = ButtonCallback  # bind: same signature as button
 
+# filepicker: receives selected path(s) or None, returns state dict
+FilepickerCallback = Callable[[str | list[str] | None], dict[str, Any]]
+
 # entry / text / scale / spinbox: receives value str (optional), returns state dict
 ValueCallback = Callable[[str], dict[str, Any]] | Callable[[], dict[str, Any]]
 
@@ -186,7 +191,7 @@ class ViewContext:
         "label", "status", "message", "button", "bind", "entry",
         "checkbutton", "radiobutton", "text", "scale", "spinbox",
         "listbox", "combobox", "treeview", "paned", "progressbar", "canvas",
-        "menubar",
+        "menubar", "filepicker",
     })
 
     def pane(self, pane_id: str) -> _PaneContext:
@@ -248,6 +253,7 @@ class TkApp:
         self._treeview_inner: dict[str, ttk.Treeview] = {}
         self._treeview_row_cache: dict[str, tuple[Any, ...]] = {}
         self._text_inner: dict[str, tk.Text] = {}
+        self._text_scrollbars: dict[str, ttk.Scrollbar] = {}
         self._text_scroll_sync: dict[str, str] = {}
         self._paned_inner: dict[str, ttk.Panedwindow] = {}
         self._pane_frames: dict[str, tk.Widget] = {}
@@ -295,6 +301,7 @@ class TkApp:
         self._grid_pack_jobs.clear()
         self._menubar_submenus.clear()
         self._text_inner.clear()
+        self._text_scrollbars.clear()
         self._text_scroll_sync.clear()
         self._a11y_last_toggle.clear()
         self._current_view = None
@@ -1463,6 +1470,9 @@ class TkApp:
         spec = self._spec(command_name)
         if spec is None or spec.on_click is None:
             return
+        if spec.kind == "filepicker":
+            self._invoke_filepicker(spec)
+            return
         values = self._entry_values_dict()
         self._state[command_name] = label
         result = self._dispatch(command_name, spec.on_click, values)
@@ -1631,6 +1641,60 @@ class TkApp:
             return fn
         return decorator
 
+    def filepicker(
+        self,
+        name: str,
+        **options: Unpack[FilepickerOptions],
+    ) -> Callable[[Callable[[Any], dict[str, Any]]], Callable[[Any], dict[str, Any]]]:
+        """Register a file picker button.
+
+        Clicking the button opens a tkinter file dialog. The selected path(s)
+        are passed to the decorated callback, which returns a state update
+        dict. ``mode`` selects the dialog type:
+
+        - ``"open"`` (default): single file open via ``askopenfilename``.
+        - ``"open_multiple"``: multiple files via ``askopenfilenames``.
+        - ``"save"``: save file via ``asksaveasfilename``.
+        - ``"directory"``: directory via ``askdirectory``.
+
+        ``title``, ``initialdir``, ``initialfile``, ``filetypes``, and
+        ``defaultextension`` are forwarded to the underlying dialog. For
+        ``filetypes`` use a sequence of ``("label", "*.ext")`` or
+        ``("label", "*.ext1 *.ext2")`` tuples.
+
+        The callback receives the selected path string, a list of strings for
+        ``"open_multiple"``, or ``None`` when the user cancels.
+
+        Example::
+
+            @app.filepicker("open_path", mode="open", title="Open file")
+            def pick_open_path(path: str | None) -> dict[str, Any]:
+                return {"open_path": path}
+        """
+        def decorator(fn: Callable[[Any], dict[str, Any]]) -> Callable[[Any], dict[str, Any]]:
+            mode = options.get("mode", "open")
+            label = options.get("label", "")
+            description = options.get("description")
+            enabled_if = options.get("enabled_if")
+            takefocus = options.get("takefocus")
+            primary = options.get("primary", False)
+            font = options.get("font")
+            extras: dict[str, Any] = {
+                "mode": mode,
+                "style": "Primary.TButton" if primary else "Secondary.TButton",
+            }
+            for opt in ("title", "initialdir", "initialfile", "filetypes", "defaultextension"):
+                value = options.get(opt)
+                if value is not None:
+                    extras[opt] = value
+            self._add_spec(WidgetSpec(
+                name=name, kind="filepicker", label_text=label, role="button",
+                description=description, on_click=fn, enabled_if=enabled_if,
+                extras=self._widget_extras(extras, takefocus=takefocus),
+            ))
+            return fn
+        return decorator
+
     def button(
         self,
         name: str,
@@ -2461,7 +2525,9 @@ class TkApp:
                         value = result
                     elif isinstance(result, dict):
                         value = result.get(spec.name, value)
-                tk_w.configure(text=str(value))  # type: ignore[call-arg]
+                target = str(value)
+                if str(tk_w.cget("text")) != target:
+                    tk_w.configure(text=target)  # type: ignore[call-arg]
             elif spec.kind == "text":
                 self._sync_text_widget(spec)
             elif spec.kind == "listbox" and spec.extras.get("items_key") is not None:
@@ -2535,7 +2601,9 @@ class TkApp:
                 tk_w = self._tk_widgets.get(spec.name)
                 if tk_w is None:
                     continue
-                tk_w.configure(text=str(update[spec.name]))  # type: ignore[call-arg]
+                target = str(update[spec.name])
+                if str(tk_w.cget("text")) != target:
+                    tk_w.configure(text=target)  # type: ignore[call-arg]
             elif spec.kind == "text" and spec.name in update:
                 self._sync_text_widget(spec)
 
@@ -2816,6 +2884,7 @@ class TkApp:
             "label": self._build_label,
             "message": self._build_message,
             "button": self._build_button,
+            "filepicker": self._build_filepicker,
             "entry": self._build_entry,
             "checkbutton": self._build_checkbutton,
             "radiobutton": self._build_radiobutton,
@@ -2956,11 +3025,28 @@ class TkApp:
             if text_a is None or text_b is None:
                 continue
 
-            def _sync_from_a(*_args: Any, source: tk.Text = text_a, target: tk.Text = text_b) -> None:
-                target.yview_moveto(source.yview()[0])
+            sb_a = self._text_scrollbars.get(name_a)
+            sb_b = self._text_scrollbars.get(name_b)
 
-            def _sync_from_b(*_args: Any, source: tk.Text = text_b, target: tk.Text = text_a) -> None:
+            def _sync_from_a(
+                *args: Any,
+                source: tk.Text = text_a,
+                target: tk.Text = text_b,
+                sb: ttk.Scrollbar | None = sb_a,
+            ) -> None:
                 target.yview_moveto(source.yview()[0])
+                if sb is not None:
+                    sb.set(*args)
+
+            def _sync_from_b(
+                *args: Any,
+                source: tk.Text = text_b,
+                target: tk.Text = text_a,
+                sb: ttk.Scrollbar | None = sb_b,
+            ) -> None:
+                target.yview_moveto(source.yview()[0])
+                if sb is not None:
+                    sb.set(*args)
 
             text_a.configure(yscrollcommand=_sync_from_a)
             text_b.configure(yscrollcommand=_sync_from_b)
@@ -3176,6 +3262,51 @@ class TkApp:
             fn = spec.on_click
             w.configure(command=lambda s=spec, f=fn: self._on_button_click(s, f))
 
+    def _invoke_filepicker(self, spec: WidgetSpec) -> None:
+        """Open the file dialog for a filepicker spec and dispatch the result."""
+        import tkinter.filedialog as fd
+
+        mode = spec.extras.get("mode", "open")
+        dialog_kw: dict[str, Any] = {}
+        for opt in ("title", "initialdir", "initialfile", "filetypes", "defaultextension"):
+            if opt in spec.extras:
+                dialog_kw[opt] = spec.extras[opt]
+
+        if mode == "open":
+            result = fd.askopenfilename(**dialog_kw)
+        elif mode == "open_multiple":
+            result = fd.askopenfilenames(**dialog_kw)
+        elif mode == "save":
+            result = fd.asksaveasfilename(**dialog_kw)
+        elif mode == "directory":
+            result = fd.askdirectory(**dialog_kw)
+        else:
+            raise ValueError(f"unknown filepicker mode {mode!r}")
+        if result == "" or result == () or result is None:
+            result = None
+        fn = spec.on_click
+        if fn is None:
+            return
+        out = self._dispatch(spec.name, fn, result)
+        if isinstance(out, dict) and out:
+            self._apply_state(out)
+
+    def _build_filepicker(self, spec: WidgetSpec, master: tk.Misc) -> None:
+        """Build a button that opens a file dialog when clicked."""
+        style = spec.extras.get("style", "Secondary.TButton")
+        overrides: dict[str, Any] = {}
+        if "font" in spec.extras:
+            overrides["font"] = spec.extras["font"]
+        if overrides:
+            style = self._derive_ttk_style(
+                style, f"Unique.{style}.{spec.name}", overrides
+            )
+        w = ttk.Button(master, text=spec.label_text or spec.name, style=style)
+        if "state" in spec.extras:
+            w.configure(state=spec.extras["state"])
+        self._tk_widgets[spec.name] = w
+        w.configure(command=lambda s=spec: self._invoke_filepicker(s))
+
     def _build_entry(self, spec: WidgetSpec, master: tk.Misc) -> None:
         e = spec.extras
         var = tk.StringVar(value="")
@@ -3301,6 +3432,7 @@ class TkApp:
         scroll.grid(row=0, column=1, sticky="ns")
         self._tk_widgets[spec.name] = container
         self._text_inner[spec.name] = w
+        self._text_scrollbars[spec.name] = scroll
 
         tags: dict[str, dict[str, Any]] | None = e.get("tags")
         if tags:
@@ -3972,6 +4104,11 @@ class TkApp:
                 d["value"] = self._state.get(sk, 0)
             if w.kind == "entry":
                 d["placeholder_as_hint"] = w.placeholder_as_hint
+            if w.kind == "filepicker":
+                d["mode"] = w.extras.get("mode", "open")
+                for opt in ("title", "initialdir", "initialfile", "filetypes", "defaultextension"):
+                    if opt in w.extras:
+                        d[opt] = w.extras[opt]
             if w.kind == "menubar":
                 d["items"] = [
                     {"label": i.get("label"), "command": i.get("command"),