Implement border (sub)title. (#2064)

* Add Widget.border_title and border_subtitle.

Related issues: #1864

* Test setting border_(sub)title.

* Add border (sub)title references to StylesCache.

These internal references will make it easier for the instance of 'StylesCache' to know which border (sub)title to use, if/when needed.

* Add method to render border label.

* Add styles to align border (sub)title.

* Render border labels.

* Update styles template.

* Make new 'render_row' parameters optional.

* Add (sub)title border snapshot tests.

* Document border (sub)title and styles.

* Pass (sub)title directly as arguments.

Get rid of the watchers to make data flow easier to follow.
Related comment: https://github.com/Textualize/textual/pull/2064/files\#r1137746697

* Tweak example.

* Fix render_border_label.

This was wrong because border labels can be composed of multiple segments if they contain multiple styles. Additionally, we want to render a single blank space of padding around the title.

* Ensure we get no label when there's no space.

* Add tests for border label rendering.

* 'render_border_label' now returns iterable of segments.

* Add label to render_row.

* Fix calling signature in tests.

* Add padding to snapshot tests.

* Fix changelog.

* Update snapshot tests.

* Update snapshot tests.

* Border labels expand if there's no corners.

* Update CHANGELOG.md

* Fix docs.

* Remove irrelevant line.

* Fix snapshot tests.

* Don't share Console among tests.

* Simplify example in styles guide.

* Avoid expensive function call when possible.

* rewording

* positive branch first

* remove wasteful indirection

* fix changelog

---------

Co-authored-by: Will McGugan <willmcgugan@gmail.com>

tests/test_styles_cache.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from rich.console import Console
 from rich.segment import Segment
 from rich.style import Style
 
@@ -40,6 +41,9 @@ def test_no_styles():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
     style = Style.from_color(bgcolor=Color.parse("green").rich_color)
@@ -67,6 +71,9 @@ def test_border():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
 
@@ -98,6 +105,9 @@ def test_padding():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
 
@@ -130,6 +140,9 @@ def test_padding_border():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
 
@@ -163,6 +176,9 @@ def test_outline():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
 
@@ -191,6 +207,9 @@ def test_crop():
         Color.parse("blue"),
         Color.parse("green"),
         content.__getitem__,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
         crop=Region(2, 2, 3, 3),
     )
@@ -227,7 +246,10 @@ def test_dirty_cache() -> None:
         Color.parse("blue"),
         Color.parse("green"),
         get_content_line,
-        Size(3, 3),
+        Console(),
+        "",
+        "",
+        content_size=Size(3, 3),
     )
     assert rendered_lines == [0, 1, 2]
     del rendered_lines[:]
@@ -252,6 +274,9 @@ def test_dirty_cache() -> None:
         Color.parse("blue"),
         Color.parse("green"),
         get_content_line,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
     assert rendered_lines == []
@@ -268,6 +293,9 @@ def test_dirty_cache() -> None:
         Color.parse("blue"),
         Color.parse("green"),
         get_content_line,
+        Console(),
+        "",
+        "",
         content_size=Size(3, 3),
     )
     assert rendered_lines == [0, 1]