Merge branch 'Textualize:main' into main

Author: saska

CHANGELOG.md

@@ -20,11 +20,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `OptionList.set_options` https://github.com/Textualize/textual/pull/6048
 - Added `TextArea.suggestion` https://github.com/Textualize/textual/pull/6048
 - Added `TextArea.placeholder` https://github.com/Textualize/textual/pull/6048
+- Added `Header.format_title` and `App.format_title` for easier customization of title in the Header https://github.com/Textualize/textual/pull/6051
 - Added `Widget.get_line_filters` and `App.get_line_filters` https://github.com/Textualize/textual/pull/6057
+- Added `Binding.Group` https://github.com/Textualize/textual/pull/6070
+- Added `DOMNode.displayed_children` https://github.com/Textualize/textual/pull/6070
+- Added `TextArea.UserInsert` message https://github.com/Textualize/textual/pull/6070
+- Added `TextArea.hide_suggestion_on_blur` boolean https://github.com/Textualize/textual/pull/6070
 
 ### Changed
 
 - Breaking change: The `renderable` property on the `Static` widget has been changed to `content`. https://github.com/Textualize/textual/pull/6041
+- Breaking change: `HeaderTitle` widget is now a static, with no `text` and `sub_text` reactives https://github.com/Textualize/textual/pull/6051
 - Breaking change: Renamed `Label` constructor argument `renderable` to `content` for consistency https://github.com/Textualize/textual/pull/6045
 - Breaking change: Optimization to line API to avoid applying background styles to widget content. In practice this means that you can no longer rely on blank Segments automatically getting the background color.
 

docs/how-to/style-inline-apps.md

@@ -19,6 +19,11 @@ The following app displays the the current time (and keeps it up to date).
 
 With Textual's default settings, this clock will be displayed in 5 lines; 3 for the digits and 2 for a top and bottom border.
 
+!!! note
+
+    Textual also adds a blank line above inline apps for padding.
+    To remove this default padding, you can set `INLINE_PADDING = 0` on your app class.
+
 You can change the height or the border with CSS and the `:inline` pseudo-selector, which only matches rules in inline mode.
 Let's update this app to remove the default border, and increase the height:
 

src/textual/_compositor.py

@@ -1132,6 +1132,8 @@ def render_full_update(self, simplify: bool = False) -> LayoutUpdate:
         crop = screen_region
         chops = self._render_chops(crop, lambda y: True)
         if simplify:
+            # Simplify is done when exporting to SVG
+            # It doesn't make things faster
             render_strips = [
                 Strip.join(chop.values()).simplify().discard_meta() for chop in chops
             ]

src/textual/_node_list.py

@@ -3,7 +3,7 @@
 import sys
 import weakref
 from operator import attrgetter
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, Sequence, overload
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Sequence, overload
 
 import rich.repr
 
@@ -14,6 +14,10 @@
     from textual.widget import Widget
 
 
+_display_getter = attrgetter("display")
+_visible_getter = attrgetter("visible")
+
+
 class DuplicateIds(Exception):
     """Raised when attempting to add a widget with an id that already exists."""
 
@@ -41,6 +45,8 @@ def __init__(self, parent: DOMNode | None = None) -> None:
         # The nodes in the list
         self._nodes: list[Widget] = []
         self._nodes_set: set[Widget] = set()
+        self._displayed_nodes: tuple[int, list[Widget]] = (-1, [])
+        self._displayed_visible_nodes: tuple[int, list[Widget]] = (-1, [])
 
         # We cache widgets by their IDs too for a quick lookup
         # Note that only widgets with IDs are cached like this, so
@@ -69,8 +75,6 @@ def updated(self) -> None:
         """Mark the nodes as having been updated."""
         self._updates += 1
         node = None if self._parent is None else self._parent()
-        if node is None:
-            return
         while node is not None and (node := node._parent) is not None:
             node._nodes._updates += 1
 
@@ -187,18 +191,29 @@ def __reversed__(self) -> Iterator[Widget]:
         return reversed(self._nodes)
 
     @property
-    def displayed(self) -> Iterable[Widget]:
+    def displayed(self) -> Sequence[Widget]:
         """Just the nodes where `display==True`."""
-        for node in self._nodes:
-            if node.display:
-                yield node
+        if self._displayed_nodes[0] != self._updates:
+            self._displayed_nodes = (
+                self._updates,
+                list(filter(_display_getter, self._nodes)),
+            )
+        return self._displayed_nodes[1]
 
     @property
-    def displayed_reverse(self) -> Iterable[Widget]:
+    def displayed_and_visible(self) -> Sequence[Widget]:
+        """Nodes with both `display==True` and `visible==True`."""
+        if self._displayed_visible_nodes[0] != self._updates:
+            self._displayed_nodes = (
+                self._updates,
+                list(filter(_visible_getter, self.displayed)),
+            )
+        return self._displayed_nodes[1]
+
+    @property
+    def displayed_reverse(self) -> Iterator[Widget]:
         """Just the nodes where `display==True`, in reverse order."""
-        for node in reversed(self._nodes):
-            if node.display:
-                yield node
+        return filter(_display_getter, reversed(self._nodes))
 
     if TYPE_CHECKING:
 
@@ -211,9 +226,11 @@ def __getitem__(self, index: slice) -> list[Widget]: ...
     def __getitem__(self, index: int | slice) -> Widget | list[Widget]:
         return self._nodes[index]
 
-    def __getattr__(self, key: str) -> object:
-        if key in {"clear", "append", "pop", "insert", "remove", "extend"}:
-            raise ReadOnlyError(
-                "Widget.children is read-only: use Widget.mount(...) or Widget.remove(...) to add or remove widgets"
-            )
-        raise AttributeError(key)
+    if not TYPE_CHECKING:
+        # This confused the type checker for some reason
+        def __getattr__(self, key: str) -> object:
+            if key in {"clear", "append", "pop", "insert", "remove", "extend"}:
+                raise ReadOnlyError(
+                    "Widget.children is read-only: use Widget.mount(...) or Widget.remove(...) to add or remove widgets"
+                )
+            raise AttributeError(key)

src/textual/app.py

@@ -94,6 +94,7 @@
 from textual.binding import Binding, BindingsMap, BindingType, Keymap
 from textual.command import CommandListItem, CommandPalette, Provider, SimpleProvider
 from textual.compose import compose
+from textual.content import Content
 from textual.css.errors import StylesheetError
 from textual.css.query import NoMatches
 from textual.css.stylesheet import RulesMap, Stylesheet
@@ -813,6 +814,8 @@ def __init__(
         self._resize_event: events.Resize | None = None
         """A pending resize event, sent on idle."""
 
+        self._size: Size | None = None
+
         self._css_update_count: int = 0
         """Incremented when CSS is invalidated."""
 
@@ -971,6 +974,27 @@ def clipboard(self) -> str:
         """
         return self._clipboard
 
+    def format_title(self, title: str, sub_title: str) -> Content:
+        """Format the title for display.
+
+        Args:
+            title: The title.
+            sub_title: The sub title.
+
+        Returns:
+            Content instance with title and subtitle.
+        """
+        title_content = Content(title)
+        sub_title_content = Content(sub_title)
+        if sub_title_content:
+            return Content.assemble(
+                title_content,
+                (" — ", "dim"),
+                sub_title_content.stylize("dim"),
+            )
+        else:
+            return title_content
+
     @contextmanager
     def batch_update(self) -> Generator[None, None, None]:
         """A context manager to suspend all repaints until the end of the batch."""
@@ -1532,6 +1556,8 @@ def size(self) -> Size:
         Returns:
             Size of the terminal.
         """
+        if self._size is not None:
+            return self._size
         if self._driver is not None and self._driver._size is not None:
             width, height = self._driver._size
         else:
@@ -4114,6 +4140,7 @@ async def _on_key(self, event: events.Key) -> None:
 
     async def _on_resize(self, event: events.Resize) -> None:
         event.stop()
+        self._size = event.size
         self._resize_event = event
 
     async def _on_app_focus(self, event: events.AppFocus) -> None:

src/textual/binding.py

@@ -66,7 +66,7 @@ class Binding:
     key_display: str | None = None
     """How the key should be shown in footer.
 
-    If None, the display of the key will use the result of `App.get_key_display`.
+    If `None`, the display of the key will use the result of `App.get_key_display`.
 
     If overridden in a keymap then this value is ignored.
     """
@@ -84,6 +84,16 @@ class Binding:
     system: bool = False
     """Make this binding a system binding, which removes it from the key panel."""
 
+    @dataclass(frozen=True)
+    class Group:
+        """A binding group causes the keys to be grouped under a single description."""
+
+        description: str = ""
+        """Description of the group."""
+
+    group: Group | None = None
+    """Optional binding group (used to group related bindings in the footer)."""
+
     def parse_key(self) -> tuple[list[str], str]:
         """Parse a key into a list of modifiers, and the actual key.
 
@@ -151,6 +161,7 @@ def make_bindings(cls, bindings: Iterable[BindingType]) -> Iterable[Binding]:
                     tooltip=binding.tooltip,
                     id=binding.id,
                     system=binding.system,
+                    group=binding.group,
                 )
 
 

src/textual/content.py

@@ -405,13 +405,12 @@ def simplify(self) -> Content:
         Returns:
             Self.
         """
-        spans = self.spans
-        if not spans:
+        if not (spans := self._spans):
             return self
-        last_span = Span(0, 0, Style())
+        last_span = Span(-1, -1, "")
         new_spans: list[Span] = []
         changed: bool = False
-        for span in self._spans:
+        for span in spans:
             if span.start == last_span.end and span.style == last_span.style:
                 last_span = new_spans[-1] = Span(last_span.start, span.end, span.style)
                 changed = True
@@ -422,6 +421,19 @@ def simplify(self) -> Content:
             self._spans[:] = new_spans
         return self
 
+    def add_spans(self, spans: Sequence[Span]) -> Content:
+        """Adds spans to this Content instance.
+
+        Args:
+            spans: A sequence of spans.
+
+        Returns:
+            A Content instance.
+        """
+        if spans:
+            return Content(self.plain, [*self._spans, *spans], self._cell_length)
+        return self
+
     def __eq__(self, other: object) -> bool:
         """Compares text only, so that markup doesn't effect sorting."""
         if isinstance(other, str):
@@ -693,7 +705,9 @@ def plain(self) -> str:
     @property
     def without_spans(self) -> Content:
         """The content with no spans"""
-        return Content(self.plain, [], self._cell_length)
+        if self._spans:
+            return Content(self.plain, [], self._cell_length)
+        return self
 
     @property
     def first_line(self) -> Content:
@@ -734,18 +748,14 @@ def __add__(self, other: Content | str) -> Content:
             offset = len(self.plain)
             content = Content(
                 self.plain + other.plain,
-                [
-                    *self._spans,
-                    *[
+                (
+                    self._spans
+                    + [
                         Span(start + offset, end + offset, style)
                         for start, end, style in other._spans
-                    ],
-                ],
-                (
-                    self.cell_length + other._cell_length
-                    if other._cell_length is not None
-                    else None
+                    ]
                 ),
+                (self.cell_length + other.cell_length),
             )
             return content
         return NotImplemented
@@ -1083,7 +1093,7 @@ def stylize(
             return self
         return Content(
             self.plain,
-            [*self._spans, Span(start, length if length < end else end, style)],
+            self._spans + [Span(start, length if length < end else end, style)],
         )
 
     def stylize_before(
@@ -1470,7 +1480,7 @@ def highlight_regex(
         self,
         highlight_regex: re.Pattern[str] | str,
         *,
-        style: Style,
+        style: Style | str,
         maximum_highlights: int | None = None,
     ) -> Content:
         """Apply a style to text that matches a regular expression.

src/textual/css/styles.py

@@ -1463,7 +1463,6 @@ def has_any_rules(self, *rule_names: str) -> bool:
         return any(inline_has_rule(name) or base_has_rule(name) for name in rule_names)
 
     def set_rule(self, rule_name: str, value: object | None) -> bool:
-        self._updates += 1
         return self._inline_styles.set_rule(rule_name, value)
 
     def get_rule(self, rule_name: str, default: object = None) -> object:
@@ -1473,7 +1472,6 @@ def get_rule(self, rule_name: str, default: object = None) -> object:
 
     def clear_rule(self, rule_name: str) -> bool:
         """Clear a rule (from inline)."""
-        self._updates += 1
         return self._inline_styles.clear_rule(rule_name)
 
     def get_rules(self) -> RulesMap:

src/textual/demo/widgets.py

@@ -587,7 +587,7 @@ class Switches(containers.VerticalGroup):
     SWITCHES_MD = """\
 ## Switches
 
-Functionally almost identical to a Checkbox, but more displays more prominently in the UI.
+Functionally almost identical to a Checkbox, but displays more prominently in the UI.
 """
     DEFAULT_CSS = """\
 Switches {    

src/textual/dom.py

@@ -10,7 +10,6 @@
 import threading
 from functools import lru_cache, partial
 from inspect import getfile
-from operator import attrgetter
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -408,6 +407,15 @@ def children(self) -> Sequence["Widget"]:
         """
         return self._nodes
 
+    @property
+    def displayed_children(self) -> Sequence[Widget]:
+        """The displayed children (where node.display==True).
+
+        Returns:
+            A sequence of widgets.
+        """
+        return self._nodes.displayed
+
     @property
     def is_empty(self) -> bool:
         """Are there no displayed children?"""
@@ -1215,15 +1223,6 @@ def ancestors(self) -> list[DOMNode]:
             add_node(node)
         return cast("list[DOMNode]", nodes)
 
-    @property
-    def displayed_children(self) -> list[Widget]:
-        """The child nodes which will be displayed.
-
-        Returns:
-            A list of nodes.
-        """
-        return list(filter(attrgetter("display"), self._nodes))
-
     def watch(
         self,
         obj: DOMNode,