Merge pull request #5999 from Textualize/empty-class

empty class

Author: willmcgugan

CHANGELOG.md

@@ -5,8 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unrleeased
+
+### Added
+
+- Added `empty` pseudo class, which applies when a widget has no displayed children https://github.com/Textualize/textual/pull/5999
+- Added `Screen.action_focus` https://github.com/Textualize/textual/pull/5999
+
+### Changed
+
+- `last-child`, `last-of-type`, `first-child`, and `first-of-type` apply to displayed children only https://github.com/Textualize/textual/pull/5999
+- `textual.compose` is now public https://github.com/Textualize/textual/pull/5999
+
 ## [5.0.1] - 2025-07-25
 
+
 ### Fixed
 
 - Fixed appending to Markdown widgets that were constructed with an existing document https://github.com/Textualize/textual/pull/5990

docs/api/compose.md

@@ -0,0 +1,5 @@
+---
+title: "textual.compose"
+---
+
+::: textual.compose

mkdocs-nav.yml

@@ -194,6 +194,7 @@ nav:
       - "api/command.md"
       - "api/constants.md"
       - "api/containers.md"
+      - "api/compose.md"
       - "api/content.md"
       - "api/coordinate.md"
       - "api/dom_node.md"

src/textual/_node_list.py

@@ -3,7 +3,7 @@
 import sys
 import weakref
 from operator import attrgetter
-from typing import TYPE_CHECKING, Any, Callable, Iterator, Sequence, overload
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, Sequence, overload
 
 import rich.repr
 
@@ -186,6 +186,20 @@ def __iter__(self) -> Iterator[Widget]:
     def __reversed__(self) -> Iterator[Widget]:
         return reversed(self._nodes)
 
+    @property
+    def displayed(self) -> Iterable[Widget]:
+        """Just the nodes where `display==True`."""
+        for node in self._nodes:
+            if node.display:
+                yield node
+
+    @property
+    def displayed_reverse(self) -> Iterable[Widget]:
+        """Just the nodes where `display==True`, in reverse order."""
+        for node in reversed(self._nodes):
+            if node.display:
+                yield node
+
     if TYPE_CHECKING:
 
         @overload

src/textual/app.py

@@ -75,7 +75,6 @@
 from textual._ansi_theme import ALABASTER, MONOKAI
 from textual._callback import invoke
 from textual._compat import cached_property
-from textual._compose import compose
 from textual._compositor import CompositorUpdate
 from textual._context import active_app, active_message_pump
 from textual._context import message_hook as message_hook_context_var
@@ -94,6 +93,7 @@
 from textual.await_remove import AwaitRemove
 from textual.binding import Binding, BindingsMap, BindingType, Keymap
 from textual.command import CommandListItem, CommandPalette, Provider, SimpleProvider
+from textual.compose import compose
 from textual.css.errors import StylesheetError
 from textual.css.query import NoMatches
 from textual.css.stylesheet import RulesMap, Stylesheet

src/textual/_compose.py renamed to src/textual/compose.py

@@ -1,17 +1,44 @@
+"""
+
+The compose method allows you to mount widgets using the same syntax as the [compose][textual.widget.Widget.compose] method.
+
+```python
+
+    def on_key(self, event:events.Key) -> None:
+
+        def add_key(key:str) -> ComposeResult:
+            with containers.HorizontalGroup():
+                yield Label("You pressed:")
+                yield Label(key)
+
+        self.mount_all(
+            compose(self, add_key(event.key)),
+        )
+
+```
+
+
+"""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from textual.app import App
+    from textual.app import App, ComposeResult
     from textual.widget import Widget
 
+__all__ = ["compose"]
+
 
-def compose(node: App | Widget) -> list[Widget]:
+def compose(
+    node: App | Widget, compose_result: ComposeResult | None = None
+) -> list[Widget]:
     """Compose child widgets.
 
     Args:
         node: The parent node.
+        compose_result: A compose result, or `None` to call `node.compose()`.
 
     Returns:
         A list of widgets.
@@ -25,7 +52,9 @@ def compose(node: App | Widget) -> list[Widget]:
     composed: list[Widget] = []
     app._compose_stacks.append(compose_stack)
     app._composed.append(composed)
-    iter_compose = iter(node.compose())
+    iter_compose = iter(
+        compose_result if compose_result is not None else node.compose()
+    )
     is_generator = hasattr(iter_compose, "throw")
     try:
         while True:

src/textual/css/_style_properties.py

@@ -783,6 +783,7 @@ class StringEnumProperty(Generic[EnumType]):
         default: The default value (or a factory thereof) of the property.
         layout: Whether to refresh the node layout on value change.
         refresh_children: Whether to refresh the node children on value change.
+        display: Does this property change display?
     """
 
     def __init__(
@@ -792,12 +793,14 @@ def __init__(
         layout: bool = False,
         refresh_children: bool = False,
         refresh_parent: bool = False,
+        display: bool = False,
     ) -> None:
         self._valid_values = valid_values
         self._default = default
         self._layout = layout
         self._refresh_children = refresh_children
         self._refresh_parent = refresh_parent
+        self._display = display
 
     def __set_name__(self, owner: StylesBase, name: str) -> None:
         self.name = name
@@ -849,6 +852,12 @@ def __set__(self, obj: StylesBase, value: EnumType | None = None):
                     ),
                 )
             if obj.set_rule(self.name, value):
+                if self._display and obj.node is not None:
+                    node = obj.node
+                    if node.parent:
+                        node._nodes.updated()
+                        node.parent._refresh_styles()
+
                 self._before_refresh(obj, value)
                 obj.refresh(
                     layout=self._layout,

src/textual/css/constants.py

@@ -80,6 +80,7 @@
     "last-child",
     "odd",
     "even",
+    "empty",
 }
 VALID_OVERLAY: Final = {"none", "screen"}
 VALID_CONSTRAIN: Final = {"inflect", "inside", "none"}

src/textual/css/styles.py

@@ -253,7 +253,7 @@ class StylesBase:
 
     node: DOMNode | None = None
 
-    display = StringEnumProperty(VALID_DISPLAY, "block", layout=True)
+    display = StringEnumProperty(VALID_DISPLAY, "block", layout=True, display=True)
     """Set the display of the widget, defining how it's rendered.
 
     Valid values are "block" or "none".

src/textual/css/stylesheet.py

@@ -464,6 +464,7 @@ def _check_rule(
         "odd",
         "even",
         "focus-within",
+        "empty",
     }
 
     def apply(
@@ -505,7 +506,7 @@ def apply(
         node._has_hover_style = "hover" in all_pseudo_classes
         node._has_focus_within = "focus-within" in all_pseudo_classes
         node._has_order_style = not all_pseudo_classes.isdisjoint(
-            {"first-of-type", "last-of-type", "first-child", "last-child"}
+            {"first-of-type", "last-of-type", "first-child", "last-child", "empty"}
         )
         node._has_odd_or_even = (
             "odd" in all_pseudo_classes or "even" in all_pseudo_classes