Textualize · willmcgugan · Nov 13, 2024 · Oct 2, 2024 · Oct 3, 2024 · Oct 3, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,20 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Added `App.theme` reactive attribute https://github.com/Textualize/textual/pull/5087
+- Added various starter themes https://github.com/Textualize/textual/pull/5087
+- Added "Change theme" command to command palette https://github.com/Textualize/textual/pull/5087
+- Added `variant` parameter to `Label` widget for quick access to common styles https://github.com/Textualize/textual/pull/5087
+- Added `App.get_theme` which returns a theme by name https://github.com/Textualize/textual/pull/5087
+- Added `App.register_theme` and `App.unregister_theme` https://github.com/Textualize/textual/pull/5087
+- Added `App.theme_changed_signal` https://github.com/Textualize/textual/pull/5087
+- Added `App.available_themes` property which returns a mapping of theme names to `Theme` instances https://github.com/Textualize/textual/pull/5087
+- Added `App.current_theme` property which returns the currently active theme object https://github.com/Textualize/textual/pull/5087
+- Added `App.get_theme_variable_defaults` which returns a mapping of theme variables to their default values https://github.com/Textualize/textual/pull/5087
+- Added `App.search` which allows bringing up a fuzzy search list of commands on-demand https://github.com/Textualize/textual/pull/5087
+- Added `App.search_themes` which allows bringing up a fuzzy search list of themes on-demand https://github.com/Textualize/textual/pull/5087
+- Added `textual.theme.ThemeProvider`, a command palette provider which returns all registered themes https://github.com/Textualize/textual/pull/5087
+- Added several new built-in CSS variables https://github.com/Textualize/textual/pull/5087
 - Added support for in-band terminal resize protocol https://github.com/Textualize/textual/pull/5217
 
 ### Changed
@@ -23,6 +37,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `textual.lazy.Reveal` https://github.com/Textualize/textual/pull/5226
 - Added `Screen.action_blur` https://github.com/Textualize/textual/pull/5226
 
+### Changed
+
+- Breaking change: Removed `App.dark` reactive attribute https://github.com/Textualize/textual/pull/5087
+- Breaking change: To improve consistency, several changes have been made to default widget CSS and the CSS variables which ship with Textual. On upgrading, your app will likely look different. All of these changes can be overidden with your own CSS. https://github.com/Textualize/textual/pull/5087
+
 ## [0.85.2] - 2024-11-02
 
 - Fixed broken focus-within https://github.com/Textualize/textual/pull/5190

diff --git a/Makefile b/Makefile
@@ -4,6 +4,10 @@ run := poetry run
 test:
 	$(run) pytest tests/ -n 16 --dist=loadgroup $(ARGS)
 
+.PHONY: testv
+testv:
+	$(run) pytest tests/ -vvv -n 16 --dist=loadgroup $(ARGS)
+
 .PHONY: test-snapshot-update
 test-snapshot-update:
 	$(run) pytest tests/ --snapshot-update -n 16 --dist=loadgroup $(ARGS)

diff --git a/docs/blog/posts/release0-38-0.md b/docs/blog/posts/release0-38-0.md
@@ -58,7 +58,7 @@ If you do want to style something outside of the widget you can set `SCOPED_CSS=
 ## Light and Dark pseudo selectors
 
 We've also made a slight quality of life improvement to the CSS, by adding `:light` and `:dark` pseudo selectors.
-This allows you to change styles depending on whether you have dark mode enabled or not.
+This allows you to change styles depending on whether the app is currently using a light or dark theme.
 
 This was possible before, just a little verbose.
 Here's how you would do it in 0.37.0:

diff --git a/docs/css_types/color.md b/docs/css_types/color.md
@@ -17,7 +17,7 @@ A bullet point summary of the formats available follows:
  - a color description in the RGB system, [with](#rgba-description) or [without](#rgb-description) opacity (e.g., `rgb(23, 78, 200)`);
  - a color description in the HSL system, [with](#hsla-description) or [without](#hsl-description) opacity (e.g., `hsl(290, 70%, 80%)`);
 
-[Textual's default themes](../guide/design.md#theme-reference) also provide many CSS variables with colors that can be used out of the box.
+[Textual's default themes](../guide/design.md) also provide many CSS variables with colors that can be used out of the box.
 
 ### Named colors
 

diff --git a/docs/examples/events/on_decorator01.py b/docs/examples/events/on_decorator01.py
@@ -16,7 +16,9 @@ def on_button_pressed(self, event: Button.Pressed) -> None:  # (1)!
         if event.button.id == "bell":
             self.bell()
         elif event.button.has_class("toggle", "dark"):
-            self.dark = not self.dark
+            self.theme = (
+                "textual-dark" if self.theme == "textual-light" else "textual-light"
+            )
         elif event.button.id == "quit":
             self.exit()
 

diff --git a/docs/examples/events/on_decorator02.py b/docs/examples/events/on_decorator02.py
@@ -20,7 +20,9 @@ def play_bell(self):
     @on(Button.Pressed, ".toggle.dark")  # (2)!
     def toggle_dark(self):
         """Called when the 'toggle dark' button is pressed."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
     @on(Button.Pressed, "#quit")  # (3)!
     def quit(self):

diff --git a/docs/examples/getting_started/console.py b/docs/examples/getting_started/console.py
@@ -10,7 +10,6 @@
 
 class ConsoleApp(App):
     def compose(self):
-        self.dark = True
         yield Static(DevConsoleHeader())
 
 

diff --git a/docs/examples/styles/background_tint.tcss b/docs/examples/styles/background_tint.tcss
@@ -2,8 +2,8 @@ Vertical {
     background: $panel;
     color: auto 90%;
 }
-#tint1 { background-tint: $foreground 0%; }
-#tint2 { background-tint: $foreground 25%; }
-#tint3 { background-tint: $foreground 50%; }
-#tint4 { background-tint: $foreground 75% }
-#tint5 { background-tint: $foreground 100% }
+#tint1 { background-tint: $text 0%; }
+#tint2 { background-tint: $text 25%; }
+#tint3 { background-tint: $text 50%; }
+#tint4 { background-tint: $text 75% }
+#tint5 { background-tint: $text 100% }
diff --git a/docs/examples/themes/colored_text.py b/docs/examples/themes/colored_text.py
@@ -0,0 +1,17 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Label
+
+COLORS = ("primary", "secondary", "accent", "warning", "error", "success")
+
+
+class ColoredText(App[None]):
+    CSS = "\n".join(f".text-{color} {{color: $text-{color};}}" for color in COLORS)
+
+    def compose(self) -> ComposeResult:
+        for color in COLORS:
+            yield Label(f"$text-{color}", classes=f"text-{color}")
+
+
+app = ColoredText()
+if __name__ == "__main__":
+    app.run()
diff --git a/docs/examples/themes/muted_backgrounds.py b/docs/examples/themes/muted_backgrounds.py
@@ -0,0 +1,20 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Label
+
+COLORS = ("primary", "secondary", "accent", "warning", "error", "success")
+
+
+class MutedBackgrounds(App[None]):
+    CSS = "\n".join(
+        f".text-{color} {{padding: 0 1; color: $text-{color}; background: ${color}-muted;}}"
+        for color in COLORS
+    )
+
+    def compose(self) -> ComposeResult:
+        for color in COLORS:
+            yield Label(f"$text-{color} on ${color}-muted", classes=f"text-{color}")
+
+
+app = MutedBackgrounds()
+if __name__ == "__main__":
+    app.run()
diff --git a/docs/examples/themes/todo_app.py b/docs/examples/themes/todo_app.py
@@ -0,0 +1,96 @@
+from itertools import cycle
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Footer, Header, Input, Label, SelectionList
+
+
+class TodoList(App[None]):
+    CSS = """
+Screen {
+    align: center middle;
+    hatch: right $foreground 10%;
+}
+#content {
+    height: auto;
+    width: 40;
+    padding: 1 2;
+}
+#header {
+    height: 1;
+    width: auto;
+    margin-bottom: 1;
+}
+.title {
+    text-style: bold;
+    padding: 0 1;
+    width: 1fr;
+}
+#overdue {
+    color: $text-error;
+    background: $error-muted;
+    padding: 0 1;
+    width: auto;
+}
+#done {
+    color: $text-success;
+    background: $success-muted;
+    padding: 0 1;
+    margin: 0 1;
+}
+#footer {
+    height: auto;
+    margin-bottom: 2;
+}
+#history-header {
+    height: 1;
+    width: auto;
+}
+#history-done {
+    width: auto;
+    padding: 0 1;
+    margin: 0 1;
+    background: $primary-muted;
+    color: $text-primary;
+}
+"""
+
+    BINDINGS = [Binding("ctrl+t", "cycle_theme", "Cycle theme")]
+    THEMES = cycle(
+        ["nord", "gruvbox", "tokyo-night", "textual-dark", "solarized-light"]
+    )
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical(id="content"):
+            with Horizontal(id="header"):
+                yield Label("Today", classes="title")
+                yield Label("1 overdue", id="overdue")
+                yield Label("1 done", id="done")
+            yield SelectionList(
+                ("Buy milk", 0),
+                ("Buy bread", 1),
+                ("Go and vote", 2, True),
+                ("Return package", 3),
+                id="todo-list",
+            )
+            with Horizontal(id="footer"):
+                yield Input(placeholder="Add a task")
+
+            with Horizontal(id="history-header"):
+                yield Label("History", classes="title")
+                yield Label("4 items", id="history-done")
+
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.action_cycle_theme()
+
+    def action_cycle_theme(self) -> None:
+        self.theme = next(self.THEMES)
+
+
+app = TodoList()
+if __name__ == "__main__":
+    app.run()
diff --git a/docs/examples/tutorial/stopwatch.py b/docs/examples/tutorial/stopwatch.py
@@ -99,7 +99,9 @@ def action_remove_stopwatch(self) -> None:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch01.py b/docs/examples/tutorial/stopwatch01.py
@@ -1,5 +1,5 @@
 from textual.app import App, ComposeResult
-from textual.widgets import Header, Footer
+from textual.widgets import Footer, Header
 
 
 class StopwatchApp(App):
@@ -14,7 +14,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch02.py b/docs/examples/tutorial/stopwatch02.py
@@ -31,7 +31,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch03.py b/docs/examples/tutorial/stopwatch03.py
@@ -32,7 +32,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch04.py b/docs/examples/tutorial/stopwatch04.py
@@ -39,7 +39,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch05.py b/docs/examples/tutorial/stopwatch05.py
@@ -59,7 +59,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/tutorial/stopwatch06.py b/docs/examples/tutorial/stopwatch06.py
@@ -82,7 +82,9 @@ def compose(self) -> ComposeResult:
 
     def action_toggle_dark(self) -> None:
         """An action to toggle dark mode."""
-        self.dark = not self.dark
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
 
 
 if __name__ == "__main__":

diff --git a/docs/examples/widgets/content_switcher.tcss b/docs/examples/widgets/content_switcher.tcss
@@ -9,19 +9,14 @@ Screen {
 }
 
 ContentSwitcher {
-    background: $panel;
     border: round $primary;
     width: 90%;
     height: 1fr;
 }
 
-DataTable {
-    background: $panel;
-}
-
 MarkdownH2 {
-    background: $primary;
+    background: $panel;
     color: yellow;
     border: none;
-    padding: 0;
+    padding: 0 1;
 }
diff --git a/docs/examples/widgets/sparkline_colors.tcss b/docs/examples/widgets/sparkline_colors.tcss
@@ -39,10 +39,10 @@ Sparkline {
 }
 
 #sxt > .sparkline--max-color {
-    color: $accent 30%;
+    color: $primary 30%;
 }
 #sxt > .sparkline--min-color {
-    color: $accent;
+    color: $primary;
 }
 
 #svt > .sparkline--max-color {

diff --git a/docs/examples/widgets/tree.py b/docs/examples/widgets/tree.py
@@ -4,7 +4,7 @@
 
 class TreeApp(App):
     def compose(self) -> ComposeResult:
-        tree: Tree[dict] = Tree("Dune")
+        tree: Tree[str] = Tree("Dune")
         tree.root.expand()
         characters = tree.root.add("Characters", expand=True)
         characters.add_leaf("Paul")

diff --git a/docs/guide/CSS.md b/docs/guide/CSS.md
@@ -327,7 +327,7 @@ The `background: green` is only applied to the Button underneath the mouse curso
 Here are some other pseudo classes:
 
 - `:blur` Matches widgets which *do not* have input focus.
-- `:dark` Matches widgets in dark mode (where `App.dark == True`).
+- `:dark` Matches widgets in dark themes (where `App.theme.dark == True`).
 - `:disabled` Matches widgets which are in a disabled state.
 - `:enabled` Matches widgets which are in an enabled state.
 - `:even` Matches a widget at an evenly numbered position within its siblings.
@@ -336,7 +336,7 @@ Here are some other pseudo classes:
 - `:focus` Matches widgets which have input focus.
 - `:inline` Matches widgets when the app is running in inline mode.
 - `:last-of-type` Matches a widget that is the last of its type amongst its siblings.
-- `:light` Matches widgets in dark mode (where `App.dark == False`).
+- `:light` Matches widgets in light themes (where `App.theme.dark == False`).
 - `:odd` Matches a widget at an oddly numbered position within its siblings.
 
 ## Combinators

diff --git a/docs/guide/command_palette.md b/docs/guide/command_palette.md
@@ -11,8 +11,8 @@ Textual will suggest commands as you type in that input.
 Press ++up++ or ++down++ to select a command from the list, and ++enter++ to invoke it.
 
 Commands are looked up via a *fuzzy* search, which means Textual will show commands that match the keys you type in the same order, but not necessarily at the start of the command.
-For instance the "Toggle light/dark mode" command will be shown if you type "to" (for **to**ggle), but you could also type "dm" (to match **d**ark **m**ode).
-This scheme allows the user to quickly get to a particular command with a minimum of key-presses.
+For instance the "Change theme" command will be shown if you type "ch" (for **ch**ange), but you could also type "th" (to match **t**heme).
+This scheme allows the user to quickly get to a particular command with fewer key-presses.
 
 
 === "Command Palette"