Border style (#2292)

* border styles

* docs for border styles

* fix tests

* tests

* tests and docs

* changelog

* implement auto

* style information fix

CHANGELOG.md

@@ -20,6 +20,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - option `--port` to the command `textual console` to specify which port the console should connect to https://github.com/Textualize/textual/pull/2258
 - `Widget.scroll_to_center` method to scroll children to the center of container widget https://github.com/Textualize/textual/pull/2255 and https://github.com/Textualize/textual/pull/2276
 - Added `TabActivated` message to `TabbedContent` https://github.com/Textualize/textual/pull/2260
+- Added "panel" border style https://github.com/Textualize/textual/pull/2292
+- Added `border-title-color`, `border-title-background`, `border-title-style` rules https://github.com/Textualize/textual/issues/2289
+- Added `border-subtitle-color`, `border-subtitle-background`, `border-subtitle-style` rules https://github.com/Textualize/textual/issues/2289
 
 ### Fixed
 

docs/examples/styles/border_title_colors.css

@@ -0,0 +1,16 @@
+Screen {
+    align: center middle;
+}
+
+Label {
+    padding: 4 8;
+    border: heavy red;
+
+    border-title-color: green;
+    border-title-background: white;
+    border-title-style: bold;
+
+    border-subtitle-color: magenta;
+    border-subtitle-background: yellow;
+    border-subtitle-style: italic;
+}

docs/examples/styles/border_title_colors.py

@@ -0,0 +1,19 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Label
+
+
+class BorderTitleApp(App):
+    CSS_PATH = "border_title_colors.css"
+
+    def compose(self) -> ComposeResult:
+        yield Label("Hello, World!")
+
+    def on_mount(self) -> None:
+        label = self.query_one(Label)
+        label.border_title = "Textual Rocks"
+        label.border_subtitle = "Textual Rocks"
+
+
+if __name__ == "__main__":
+    app = BorderTitleApp()
+    app.run()

docs/snippets/border_title_color.md

@@ -0,0 +1,18 @@
+The following examples demonstrates customization of the border color and text style rules.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/border_title_colors.py"}
+    ```
+
+=== "border_title_colors.py"
+
+    ```python
+    --8<-- "docs/examples/styles/border_title_colors.py"
+    ```
+
+=== "border_title_colors.css"
+
+    ```sass
+    --8<-- "docs/examples/styles/border_title_colors.css"
+    ```

docs/snippets/see_also_border.md

@@ -0,0 +1,9 @@
+- [`border-title-align`](./border_title_align.md) to set the title's alignment.
+- [`border-title-color`](./border_subtitle_color.md) to set the title's color.
+- [`border-title-background`](./border_subtitle_background.md) to set the title's background color.
+- [`border-title-style`](./border_subtitle_style.md) to set the title's text style.
+
+- [`border-subtitle-align`](./border_subtitle_align.md) to set the sub-title's alignment.
+- [`border-subtitle-color`](./border_subtitle_color.md) to set the sub-title's color.
+- [`border-subtitle-background`](./border_subtitle_background.md) to set the sub-title's background color.
+- [`border-subtitle-style`](./border_subtitle_style.md) to set the sub-title's text style.

docs/styles/align.md

@@ -13,12 +13,7 @@ align-vertical: <a href="../../css_types/vertical">&lt;vertical&gt;</a>;
 
 The `align` style takes a [`<horizontal>`](../../css_types/horizontal) followed by a [`<vertical>`](../../css_types/vertical).
 
-You can specify the alignment of children on both the horizontal and vertical axes at the same time,
-or on each of the axis separately.
-To specify alignment on a single axis, use the respective style and type:
-
- - `align-horizontal` takes a [`<horizontal>`](../../css_types/horizontal) and does alignment along the horizontal axis; and
- - `align-vertical` takes a [`<vertical>`](../../css_types/vertical) and does alignment along the vertical axis.
+You can also set the alignment for each axis individually with `align-horizontal` and `align-vertical`.
 
 ## Examples
 

docs/styles/border.md

@@ -2,9 +2,11 @@
 
 The `border` style enables the drawing of a box around a widget.
 
+A border style may also be applied to individual edges with `border-top`, `border-right`, `border-bottom`, and `border-left`.
+
 !!! note
 
-    Due to a Textual limitation, [`border`](./border.md) and [`outline`](./outline.md) cannot coexist in the same edge of a widget.
+    [`border`](./border.md) and [`outline`](./outline.md) cannot coexist in the same edge of a widget.
 
 ## Syntax
 
@@ -17,31 +19,10 @@ border-bottom: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href=".
 border-left: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>]];
 --8<-- "docs/snippets/syntax_block_end.md"
 
-The `border` style accepts an optional [`<border>`](../../css_types/border) that sets the visual style of the widget border, an optional [`<color>`](../../css_types/color) to set the color of the border, and an optional [`<percentage>`](../../css_types/percentage) to specify the color transparency.
-
-Borders may also be set individually for the four edges of a widget with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
-
-### Multiple edge rules
-
-If multiple border styles target the same edge, the last style that targets a specific edge is the one that is applied to that edge.
-For example, consider the CSS below:
-
-```sass
-Static {
-    border-top: dashed red;
-    border: solid green;  /* overrides the border-top rule above */
-    /* Change the border but just for the bottom edge: */
-    border-bottom: double blue;
-}
-```
-
-The CSS snippet above will add a solid green border around `Static` widgets, except for the bottom edge, which will be double blue.
+In CSS, the border is set with a [border style](./border.md) and a color. Both are optional. An optional percentage may be added to blend the border with the background color.
 
-### Defaults
+In Python, the border is set with a tuple of [border style](./border.md) and a color.
 
-If `<color>` is specified but `<border>` is not, it defaults to `"solid"`.
-If `<border>` is specified but `<color>`is not, it defaults to green (RGB color `"#00FF00"`).
-If `<percentage>` is not specified it defaults to `100%`.
 
 ## Border command
 
@@ -128,3 +109,4 @@ widget.styles.border_left = ("outer", "red")
 
  - [`box-sizing`](./box_sizing.md) to specify how to account for the border in a widget's dimensions.
  - [`outline`](./outline.md) to add an outline around the content of a widget.
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_subtitle_align.md

@@ -60,3 +60,7 @@ widget.styles.border_subtitle_align = "left"
 widget.styles.border_subtitle_align = "center"
 widget.styles.border_subtitle_align = "right"
 ```
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_subtitle_background.md

@@ -0,0 +1,34 @@
+# Border-subtitle-background
+
+The `border-subtitle-background` style sets the *background* color of the [border_subtitle][textual.widget.Widget.border_subtitle].
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-subtitle-background: (<a href="../../css_types/color">&lt;color&gt;</a> | auto) [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+
+## CSS
+
+```sass
+border-subtitle-background: blue;
+```
+
+## Python
+
+```python
+widget.styles.border_subtitle_background = "blue"
+```
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_subtitle_color.md

@@ -0,0 +1,33 @@
+# Border-subtitle-color
+
+The `border-subtitle-color` style sets the color of the [border_subtitle][textual.widget.Widget.border_subtitle].
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-subtitle-color: (<a href="../../css_types/color">&lt;color&gt;</a> | auto) [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+
+## CSS
+
+```sass
+border-subtitle-color: red;
+```
+
+## Python
+
+```python
+widget.styles.border_subtitle_color = "red"
+```
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_subtitle_style.md

@@ -0,0 +1,35 @@
+# Border-subtitle-style
+
+The `border-subtitle-style` style sets the text style of the [border_subtitle][textual.widget.Widget.border_subtitle].
+
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-subtitle-style: <a href="../../css_types/text_style">&lt;text-style&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+## CSS
+
+```sass
+border-subtitle-style: bold underline;
+```
+
+## Python
+
+```python
+widget.styles.border_subtitle_style = "bold underline"
+```
+
+
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_title_align.md

@@ -60,3 +60,7 @@ widget.styles.border_title_align = "left"
 widget.styles.border_title_align = "center"
 widget.styles.border_title_align = "right"
 ```
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_title_background.md

@@ -0,0 +1,33 @@
+# Border-title-background
+
+The `border-title-background` style sets the *background* color of the [border_title][textual.widget.Widget.border_title].
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-title-background: (<a href="../../css_types/color">&lt;color&gt;</a> | auto) [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+## CSS
+
+```sass
+border-title-background: blue;
+```
+
+## Python
+
+```python
+widget.styles.border_title_background = "blue"
+```
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_title_color.md

@@ -0,0 +1,31 @@
+# Border-title-color
+
+The `border-title-color` style sets the color of the [border_title][textual.widget.Widget.border_title].
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-title-color: (<a href="../../css_types/color">&lt;color&gt;</a> | auto) [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+--8<-- "docs/snippets/syntax_block_end.md"
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+## CSS
+
+```sass
+border-title-color: red;
+```
+
+## Python
+
+```python
+widget.styles.border_title_color = "red"
+```
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/border_title_style.md

@@ -0,0 +1,35 @@
+# Border-title-style
+
+The `border-title-style` style sets the text style of the [border_title][textual.widget.Widget.border_title].
+
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+border-title-style: <a href="../../css_types/text_style">&lt;text-style&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+
+## Example
+
+--8<-- "docs/snippets/border_title_color.md"
+
+
+## CSS
+
+```sass
+border-title-style: bold underline;
+```
+
+## Python
+
+```python
+widget.styles.border_title_style = "bold underline"
+```
+
+
+
+## See also
+
+--8<-- "docs/snippets/see_also_border.md"

docs/styles/outline.md

@@ -4,7 +4,7 @@ The `outline` style enables the drawing of a box around the content of a widget,
 
 !!! note
 
-    Due to a Textual limitation, [`border`](./border.md) and [`outline`](./outline.md) cannot coexist in the same edge of a widget.
+    [`border`](./border.md) and [`outline`](./outline.md) cannot coexist in the same edge of a widget.
 
 ## Syntax
 

docs/styles/text_style.md

@@ -1,6 +1,6 @@
 # Text-style
 
-The `text-style` sets the style for the text in a widget.
+The `text-style` style sets the style for the text in a widget.
 
 ## Syntax