feat: control selected file or directory externally in FileBrowser

maartenbreddels · maartenbreddels · commit 73a26dde9dd9 · 2025-06-17T17:48:46.000+02:00
diff --git a/solara/components/file_browser.py b/solara/components/file_browser.py
@@ -1,7 +1,8 @@
 import os
 from os.path import isfile, join
 from pathlib import Path
-from typing import Callable, Dict, List, Optional, Union, cast
+from typing import Callable, Dict, List, Optional, TypeVar, Union, cast
+import logging
 
 import humanize
 import ipyvuetify as vy
@@ -10,6 +11,9 @@
 import solara
 from solara.components import Div
 
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
 
 def list_dir(path, filter: Callable[[Path], bool] = lambda x: True, directory_first: bool = False) -> List[dict]:
     def mk_item(n):
@@ -48,9 +52,30 @@ def __contains__(self, name):
         return name in [k["name"] for k in self.files]
 
 
+def use_reactive_or_value(
+    value: Union[T, solara.Reactive[T]], on_value: Optional[Callable[[T], None]] = None, value_name="value", on_value_name="on_value", use_internal_value=False
+):
+    def hookup_on_value():
+        if isinstance(value, solara.Reactive) and on_value:
+            return value.subscribe(on_value)
+
+    solara.use_effect(hookup_on_value, [isinstance(value, solara.Reactive), on_value])
+    internal_value, set_internal_value = solara.use_state(value.value if isinstance(value, solara.Reactive) else value)
+    if use_internal_value:
+        return internal_value, set_internal_value
+    if isinstance(value, solara.Reactive):
+        return value.value, value.set
+    elif on_value:
+        return value, on_value
+    else:
+        logger.warning("You should provide an %s callback if you are not using a reactive value, otherwise %s input will not update", on_value_name, value_name)
+        return value, lambda x: None
+
+
 @solara.component
 def FileBrowser(
     directory: Union[None, str, Path, solara.Reactive[Path]] = None,
+    selected: Union[None, Path, solara.Reactive[Optional[Path]]] = None,
     on_directory_change: Optional[Callable[[Path], None]] = None,
     on_path_select: Optional[Callable[[Optional[Path]], None]] = None,
     on_file_open: Optional[Callable[[Path], None]] = None,
@@ -75,7 +100,8 @@ def FileBrowser(
 
     ## Arguments
 
-     * `directory`: The directory to start in. If `None` the current working directory is used.
+     * `directory`: The directory to start in. If `None`, the current working directory is used.
+     * `selected`: The selected file or directory. If `None`, no file or directory is selected (requires `can_select=True`).
      * `on_directory_change`: Depends on mode, see above.
      * `on_path_select`: Depends on mode, see above.
      * `on_file_open`: Depends on mode, see above.
@@ -90,13 +116,30 @@ def FileBrowser(
         directory = os.getcwd()  # pragma: no cover
     if isinstance(directory, str):
         directory = Path(directory)
+    # directory = directory.resolve()
     current_dir = solara.use_reactive(directory)
-    selected, set_selected = solara.use_state(None)
     double_clicked, set_double_clicked = solara.use_state(None)
     warning, set_warning = solara.use_state(cast(Optional[str], None))
     scroll_pos_stack, set_scroll_pos_stack = solara.use_state(cast(List[int], []))
     scroll_pos, set_scroll_pos = solara.use_state(0)
-    selected, set_selected = solara.use_state(None)
+    selected_private, set_selected_private = use_reactive_or_value(
+        selected,
+        on_value=on_path_select if can_select else lambda x: None,
+        value_name="selected",
+        on_value_name="on_path_select",
+        use_internal_value=not can_select,
+    )
+    # remove so we don't accidentally use it
+    del selected
+
+    def sync_directory_from_selected():
+        if selected_private is not None:
+            # if we select a file, we need to make sure the directory is correct
+            # NOTE: although we expect a Path, abuse might make it a string
+            if isinstance(selected_private, Path):
+                current_dir.value = selected_private.resolve().parent
+
+    solara.use_effect(sync_directory_from_selected, [selected_private])
 
     def change_dir(new_dir: Path):
         if os.access(new_dir, os.R_OK):
@@ -121,7 +164,7 @@ def on_item(item, double_click):
                     last_pos = scroll_pos_stack[-1]
                     set_scroll_pos_stack(scroll_pos_stack[:-1])
                     set_scroll_pos(last_pos)
-                set_selected(None)
+                set_selected_private(None)
                 set_double_clicked(None)
                 if on_path_select and can_select:
                     on_path_select(None)
@@ -142,7 +185,7 @@ def on_item(item, double_click):
                 if change_dir(path):
                     set_scroll_pos_stack(scroll_pos_stack + [scroll_pos])
                     set_scroll_pos(0)
-                set_selected(None)
+                set_selected_private(None)
             set_double_clicked(None)
             if on_path_select and can_select:
                 on_path_select(None)
@@ -153,7 +196,7 @@ def on_item(item, double_click):
             raise RuntimeError("Combination should not happen")  # pragma: no cover
 
     def on_click(item):
-        set_selected(item)
+        set_selected_private(item["name"] if item else None)
         on_item(item, False)
 
     def on_double_click(item):
@@ -163,12 +206,20 @@ def on_double_click(item):
         # otherwise we can ignore it, single click will handle it
 
     files = [{"name": "..", "is_file": False}] + list_dir(current_dir.value, filter=filter, directory_first=directory_first)
+    clicked = (
+        {
+            "name": selected_private.name if isinstance(selected_private, Path) else selected_private,
+            "is_file": isinstance(selected_private, Path),
+            "size": None,
+        }
+        if selected_private is not None
+        else None
+    )
     with Div(class_="solara-file-browser") as main:
         Div(children=[str(current_dir.value.resolve())])
         FileListWidget.element(
             files=files,
-            selected=selected,
-            clicked=selected,
+            clicked=clicked,
             on_clicked=on_click,
             double_clicked=double_clicked,
             on_double_clicked=on_double_click,
diff --git a/solara/website/pages/documentation/components/input/file_browser.py b/solara/website/pages/documentation/components/input/file_browser.py
@@ -2,29 +2,37 @@
 
 from pathlib import Path
 from typing import Optional, cast
-
+import random
 import solara
 from solara.website.utils import apidoc
 
+opened = solara.reactive(cast(Optional[Path], None))
+selected = solara.reactive(cast(Optional[Path], None))
+directory = solara.reactive(Path("~").expanduser())
+can_select = solara.reactive(False)
+
 
 @solara.component
 def Page():
-    file, set_file = solara.use_state(cast(Optional[Path], None))
-    path, set_path = solara.use_state(cast(Optional[Path], None))
-    directory, set_directory = solara.use_state(Path("~").expanduser())
-
-    can_select = solara.ui_checkbox("Enable select")
-
     def reset_path():
-        set_path(None)
-        set_file(None)
+        opened.value = None
+        selected.value = None
+
+    def select_random_file():
+        files = list(directory.value.glob("*"))
+        if files:
+            selected.value = random.choice(files)
 
     # reset path and file when can_select changes
-    solara.use_memo(reset_path, [can_select])
-    solara.FileBrowser(directory, on_directory_change=set_directory, on_path_select=set_path, on_file_open=set_file, can_select=can_select)
+    solara.use_memo(reset_path, [can_select.value])
+    solara.Checkbox(label="Enable select", value=can_select)
+    solara.FileBrowser(directory, selected=selected, on_file_open=opened.set, can_select=can_select.value)
     solara.Info(f"You are in directory: {directory}")
-    solara.Info(f"You selected path: {path}")
-    solara.Info(f"You opened file: {file}")
+    solara.Info(f"You selected path: {selected}")
+    solara.Info(f"You opened file: {opened}")
+
+    if can_select.value:
+        solara.Button(label="Select random file", on_click=select_random_file)
 
 
 __doc__ += apidoc(solara.FileBrowser.f)  # type: ignore
diff --git a/tests/unit/file_browser_test.py b/tests/unit/file_browser_test.py
@@ -1,6 +1,7 @@
 import platform
 import unittest.mock
 from pathlib import Path
+from typing import Optional, cast
 
 import pytest
 
@@ -22,7 +23,7 @@ def Test():
             HERE.parent, on_path_select=on_path_select, on_directory_change=on_directory_change, on_file_open=on_file_open, on_file_name=on_file_name
         )
 
-    div, rc = solara.render_fixed(Test())
+    div, rc = solara.render_fixed(Test(), handle_error=False)
     on_directory_change.assert_not_called()
     on_file_open.assert_not_called()
     on_path_select.assert_not_called()
@@ -149,10 +150,12 @@ def test_file_browser_no_access(tmpdir: Path):
 
     @solara.component
     def Test():
-        return solara.FileBrowser(tmpdir, on_path_select=on_path_select, on_directory_change=on_directory_change, on_file_open=on_file_open, can_select=True)
+        return solara.FileBrowser(
+            Path(tmpdir), on_path_select=on_path_select, on_directory_change=on_directory_change, on_file_open=on_file_open, can_select=True
+        )
 
     try:
-        div, rc = solara.render_fixed(Test())
+        div, rc = solara.render_fixed(Test(), handle_error=False)
 
         list: solara.components.file_browser.FileListWidget = div.children[1]
         # select is ok
@@ -179,7 +182,7 @@ def Test():
     list: solara.components.file_browser.FileListWidget = div.children[1]
     items = list.files
     names = {k["name"] for k in items}
-    assert names == {"unit", "ui", "docs", "integration", "pyinstaller", ".."}
+    assert names.issuperset({"unit", "ui", "docs", "integration", "pyinstaller", ".."})
 
 
 def test_file_browser_test_change_directory():
@@ -212,7 +215,7 @@ def set_directory(path: Path) -> None:
     file_list.observe(mock, "files")
     items = file_list.files
     names = {k["name"] for k in items}
-    assert names == {"unit", "ui", "docs", "integration", "pyinstaller", ".."}
+    assert names.issuperset({"unit", "ui", "docs", "integration", "pyinstaller", ".."})
     file_list.test_click("..")
     assert mock.call_count == 0
     file_list.test_click("integration")
@@ -233,3 +236,41 @@ def Test():
     list.test_click("..")
     files_parent = {k["name"] for k in list.files}
     assert files_parent != files
+
+
+def test_file_browser_programmatic_select():
+    # using a reactive value to select a file
+    selected = solara.reactive(cast(Optional[Path], None))
+
+    @solara.component
+    def Test():
+        return solara.FileBrowser(HERE.parent, selected=selected, can_select=True)
+
+    div, rc = solara.render_fixed(Test(), handle_error=False)
+    list: solara.components.file_browser.FileListWidget = div.children[1]
+    files = list.files.copy()
+    assert list.clicked is None
+    selected.value = HERE.parent / "file_browser_test.py"
+    assert list.clicked is not None
+    assert list.clicked["name"] == "file_browser_test.py"
+    list.test_click("..", double_click=True)
+    assert list.files != files
+    assert selected.value is None
+
+    selected.value = None
+
+    # passing selected as a value (non reactive)
+    @solara.component
+    def Test2():
+        return solara.FileBrowser(HERE.parent, selected=selected.value, on_path_select=selected.set, can_select=True)
+
+    div, rc = solara.render_fixed(Test2(), handle_error=False)
+    list = div.children[1]
+    files = list.files.copy()
+    assert list.clicked is None
+    selected.value = HERE.parent / "file_browser_test.py"
+    assert list.clicked is not None
+    assert list.clicked["name"] == "file_browser_test.py"
+    list.test_click("..", double_click=True)
+    assert list.files != files
+    assert selected.value is None
