Repository: Textualize/textual

Issue:
AUTO_FOCUS on App should apply to screen
If you don't define a screen, there is no way to set `AUTO_FOCUS`. We should make `AUTO_FOCUS` on App apply to the default screen.


Discussion:
I tought about that but I concluded that if you want a non-default auto focus, you should create your own screen.
The default screen _has_ limitations and is just a convenience, right?

If you still want `App.AUTO_FOCUS`, isn't there a possibility for people to think that `App.AUTO_FOCUS` should apply to all screens in the app?
In other words, I think it is weird to have `App.AUTO_FOCUS` to be special-cased.
“Special cases aren't special enough to break the rules.”

I suggest:

 - `App.AUTO_FOCUS = "*"` by default;
 - `Screen.AUTO_FOCUS = None` by default;

The auto focus is then taken from the app's and the screen's, with the screen's taking precedence if it is not `None`.
@willmcgugan pinging you explicitly to ask for your feedback on this ^
How then would you disable AUTO_FOCUS on a screen? Set it to empty string?
After some discussion, we're going with this:

 - `App.AUTO_FOCUS` defaults to `"*"`;
 - `Screen.AUTO_FOCUS` defaults to `None`;
 - Setting `AUTO_FOCUS` to `""` explicitly disables it; and
 - Setting `AUTO_FOCUS` to `None` (on a screen) means we “inherit” the value of `AUTO_FOCUS` from the app.

Resolving patch:
diff --git a/src/textual/app.py b/src/textual/app.py
--- a/src/textual/app.py
+++ b/src/textual/app.py
@@ -275,6 +275,14 @@ class MyApp(App[None]):
     """
     SCREENS: ClassVar[dict[str, Screen | Callable[[], Screen]]] = {}
     """Screens associated with the app for the lifetime of the app."""
+
+    AUTO_FOCUS: ClassVar[str | None] = "*"
+    """A selector to determine what to focus automatically when a screen is activated.
+
+    The widget focused is the first that matches the given [CSS selector](/guide/queries/#query-selectors).
+    Setting to `None` or `""` disables auto focus.
+    """
+
     _BASE_PATH: str | None = None
     CSS_PATH: ClassVar[CSSPathType | None] = None
     """File paths to load CSS from."""
diff --git a/src/textual/screen.py b/src/textual/screen.py
--- a/src/textual/screen.py
+++ b/src/textual/screen.py
@@ -94,11 +94,12 @@ def __call__(self, result: ScreenResultType) -> None:
 class Screen(Generic[ScreenResultType], Widget):
     """The base class for screens."""
 
-    AUTO_FOCUS: ClassVar[str | None] = "*"
+    AUTO_FOCUS: ClassVar[str | None] = None
     """A selector to determine what to focus automatically when the screen is activated.
 
     The widget focused is the first that matches the given [CSS selector](/guide/queries/#query-selectors).
-    Set to `None` to disable auto focus.
+    Set to `None` to inherit the value from the screen's app.
+    Set to `""` to disable auto focus.
     """
 
     DEFAULT_CSS = """
@@ -680,8 +681,9 @@ def _on_screen_resume(self) -> None:
         size = self.app.size
         self._refresh_layout(size, full=True)
         self.refresh()
-        if self.AUTO_FOCUS is not None and self.focused is None:
-            for widget in self.query(self.AUTO_FOCUS):
+        auto_focus = self.app.AUTO_FOCUS if self.AUTO_FOCUS is None else self.AUTO_FOCUS
+        if auto_focus and self.focused is None:
+            for widget in self.query(auto_focus):
                 if widget.focusable:
                     self.set_focus(widget)
                     break


Test patch:
diff --git a/tests/test_screens.py b/tests/test_screens.py
--- a/tests/test_screens.py
+++ b/tests/test_screens.py
@@ -153,7 +153,9 @@ async def test_screens():
     await app._shutdown()
 
 
-async def test_auto_focus():
+async def test_auto_focus_on_screen_if_app_auto_focus_is_none():
+    """Setting app.AUTO_FOCUS = `None` means it is not taken into consideration."""
+
     class MyScreen(Screen[None]):
         def compose(self):
             yield Button()
@@ -161,10 +163,11 @@ def compose(self):
             yield Input(id="two")
 
     class MyApp(App[None]):
-        pass
+        AUTO_FOCUS = None
 
     app = MyApp()
     async with app.run_test():
+        MyScreen.AUTO_FOCUS = "*"
         await app.push_screen(MyScreen())
         assert isinstance(app.focused, Button)
         app.pop_screen()
@@ -193,6 +196,80 @@ class MyApp(App[None]):
         assert app.focused.id == "two"
 
 
+async def test_auto_focus_on_screen_if_app_auto_focus_is_disabled():
+    """Setting app.AUTO_FOCUS = `None` means it is not taken into consideration."""
+
+    class MyScreen(Screen[None]):
+        def compose(self):
+            yield Button()
+            yield Input(id="one")
+            yield Input(id="two")
+
+    class MyApp(App[None]):
+        AUTO_FOCUS = ""
+
+    app = MyApp()
+    async with app.run_test():
+        MyScreen.AUTO_FOCUS = "*"
+        await app.push_screen(MyScreen())
+        assert isinstance(app.focused, Button)
+        app.pop_screen()
+
+        MyScreen.AUTO_FOCUS = None
+        await app.push_screen(MyScreen())
+        assert app.focused is None
+        app.pop_screen()
+
+        MyScreen.AUTO_FOCUS = "Input"
+        await app.push_screen(MyScreen())
+        assert isinstance(app.focused, Input)
+        assert app.focused.id == "one"
+        app.pop_screen()
+
+        MyScreen.AUTO_FOCUS = "#two"
+        await app.push_screen(MyScreen())
+        assert isinstance(app.focused, Input)
+        assert app.focused.id == "two"
+
+        # If we push and pop another screen, focus should be preserved for #two.
+        MyScreen.AUTO_FOCUS = None
+        await app.push_screen(MyScreen())
+        assert app.focused is None
+        app.pop_screen()
+        assert app.focused.id == "two"
+
+
+async def test_auto_focus_inheritance():
+    """Setting app.AUTO_FOCUS = `None` means it is not taken into consideration."""
+
+    class MyScreen(Screen[None]):
+        def compose(self):
+            yield Button()
+            yield Input(id="one")
+            yield Input(id="two")
+
+    class MyApp(App[None]):
+        pass
+
+    app = MyApp()
+    async with app.run_test():
+        MyApp.AUTO_FOCUS = "Input"
+        MyScreen.AUTO_FOCUS = "*"
+        await app.push_screen(MyScreen())
+        assert isinstance(app.focused, Button)
+        app.pop_screen()
+
+        MyScreen.AUTO_FOCUS = None
+        await app.push_screen(MyScreen())
+        assert isinstance(app.focused, Input)
+        app.pop_screen()
+
+        MyScreen.AUTO_FOCUS = ""
+        await app.push_screen(MyScreen())
+        assert app.focused is None
+        app.pop_screen()
+
+
 async def test_auto_focus_skips_non_focusable_widgets():
     class MyScreen(Screen[None]):
         def compose(self):