Merge pull request #6013 from Textualize/stream-layout

Stream layout

Author: willmcgugan

.gitignore

@@ -29,6 +29,7 @@ lib/
 lib64/
 parts/
 sdist/
+dist/
 var/
 wheels/
 *.egg-info/

CHANGELOG.md

@@ -5,6 +5,12 @@ 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/).
 
+## Unreleased
+
+### Added
+
+- Added a 'stream' layout, which is a lot like vertical but with fewer supported rules (which is why it is faster), will remain undocumented for now. https://github.com/Textualize/textual/pull/6013
+
 ## [5.1.1] - 2025-07-21
 
 ### Fixed

src/textual/css/constants.py

@@ -28,7 +28,7 @@
     "wide",
 }
 VALID_EDGE: Final = {"top", "right", "bottom", "left", "none"}
-VALID_LAYOUT: Final = {"vertical", "horizontal", "grid"}
+VALID_LAYOUT: Final = {"vertical", "horizontal", "grid", "stream"}
 
 VALID_BOX_SIZING: Final = {"border-box", "content-box"}
 VALID_OVERFLOW: Final = {"scroll", "hidden", "auto"}

src/textual/css/styles.py

@@ -284,7 +284,7 @@ class StylesBase:
     layout = LayoutProperty()
     """Set the layout of the widget, defining how it's children are laid out.
     
-    Valid values are "grid", "horizontal", and "vertical" or None to clear any layout
+    Valid values are "grid", "stream", "horizontal", or "vertical" or None to clear any layout
     that was set at runtime.
 
     Raises:

src/textual/layouts/factory.py

@@ -3,12 +3,14 @@
 from textual.layout import Layout
 from textual.layouts.grid import GridLayout
 from textual.layouts.horizontal import HorizontalLayout
+from textual.layouts.stream import StreamLayout
 from textual.layouts.vertical import VerticalLayout
 
 LAYOUT_MAP: dict[str, type[Layout]] = {
     "horizontal": HorizontalLayout,
     "grid": GridLayout,
     "vertical": VerticalLayout,
+    "stream": StreamLayout,
 }
 
 

src/textual/layouts/stream.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.geometry import NULL_OFFSET, Region, Size
+from textual.layout import ArrangeResult, Layout, WidgetPlacement
+
+if TYPE_CHECKING:
+
+    from textual.widget import Widget
+
+
+class StreamLayout(Layout):
+    """A cut down version of the vertical layout.
+
+    The stream layout is faster, but has a few limitations compared to the vertical layout.
+
+    - All widgets are the full width (as if their widget is `1fr`).
+    - All widgets have an effective height of `auto`.
+    - `max-height` is supported, but only if it is a units value, all other extrema rules are ignored.
+    - No absolute positioning.
+    - No overlay: screen.
+    - Layers are ignored.
+
+    The primary use of `layout: stream` is for a long list of widgets in a scrolling container, such as
+    what you might expect from a LLM chat-bot. The speed improvement will only be significant with a lot of
+    child widgets, so stick to vertical layouts unless you see any slowdown.
+
+    """
+
+    name = "stream"
+
+    def arrange(
+        self, parent: Widget, children: list[Widget], size: Size, greedy: bool = True
+    ) -> ArrangeResult:
+        parent.pre_layout(self)
+        if not children:
+            return []
+        viewport = parent.app.size
+
+        _Region = Region
+        _WidgetPlacement = WidgetPlacement
+
+        placements: list[WidgetPlacement] = []
+        width = size.width
+        first_child_styles = children[0].styles
+        y = 0
+        previous_margin = first_child_styles.margin.top
+        null_offset = NULL_OFFSET
+
+        for widget in children:
+            styles = widget.styles.base
+            margin = styles.margin
+            gutter_width, gutter_height = styles.gutter.totals
+            top, right, bottom, left = margin
+            y += max(top, previous_margin)
+            previous_margin = bottom
+            height = (
+                widget.get_content_height(size, viewport, width - gutter_width)
+                + gutter_height
+            )
+            if (max_height := styles.max_height) is not None and max_height.is_cells:
+                height = min(height, int(max_height.value))
+            placements.append(
+                _WidgetPlacement(
+                    _Region(left, y, width - (left + right), height),
+                    null_offset,
+                    margin,
+                    widget,
+                    0,
+                    False,
+                    False,
+                    False,
+                )
+            )
+            y += height
+
+        return placements

src/textual/widget.py

@@ -721,7 +721,7 @@ def anchor(self, anchor: bool = True) -> None:
         """
         self._anchored = anchor
         if anchor:
-            self.scroll_end()
+            self.scroll_end(immediate=True, animate=False)
 
     def release_anchor(self) -> None:
         """Release the [anchor][textual.widget.Widget].

tests/snapshot_tests/__snapshots__/test_snapshots/test_stream_layout.svg

@@ -4502,3 +4502,39 @@ def compose(self) -> ComposeResult:
                 pass
 
     assert snap_compare(EmptyApp())
+
+
+def test_stream_layout(snap_compare):
+    """Test stream layout.
+
+    You should see 3 blue labels.
+    The topmost should be a single line.
+    The middle should be two lines.
+    The last should be three lines.
+    There will be a one character margin between them.
+
+    """
+
+    class StreamApp(App):
+        CSS = """
+        VerticalScroll {            
+            layout: stream;
+            Label {
+                background: blue;
+                margin: 1;
+            }
+            #many-lines {
+                max-height: 3;
+            }
+        }
+        """
+
+        def compose(self) -> ComposeResult:
+            with VerticalScroll():
+                yield Label("Hello")
+                yield Label("foo\nbar")
+                yield Label(
+                    "\n".join(["Only 3 lines should be visible"] * 100), id="many-lines"
+                )
+
+    assert snap_compare(StreamApp())