Keyline rule (#3669)

* canvas

* imports

* more box drawing

* lines

* lines

* box drawing table

* fix box table

* tweak test

* canvas color

* simplify canvas

* optimization

* clipping

* render experiment

* keyline css

* tests

* don't draw around invisible widgets

* optimize

* snapshot test

* docs and examples

* tab size

* disclaimer

* docs

* changelog

* snapshots

* accidental add

* rename for consistency

* simplify color

* docstrings

* comment

* snapshots

* micro optimize

* micro-optimization

* typing

* set over list

* remove comment

* docstring

* punctuation

* Update docs/styles/keyline.md

Co-authored-by: Darren Burns <[email protected]>

---------

Co-authored-by: Darren Burns <[email protected]>

CHANGELOG.md

@@ -12,10 +12,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Fixed mouse targeting issue in `TextArea` when tabs were not fully expanded https://github.com/Textualize/textual/pull/3725
 
+### Added
+
+- Added experimental Canvas class https://github.com/Textualize/textual/pull/3669/
+- Added `keyline` rule https://github.com/Textualize/textual/pull/3669/
+
 ### Changed
 
 - Optimized startup time https://github.com/Textualize/textual/pull/3753
 
+
 ## [0.42.0] - 2023-11-22
 
 ### Fixed

docs/css_types/keyline.md

@@ -0,0 +1,30 @@
+# <keyline>
+
+The `<keyline>` CSS type represents a line style used in the [keyline](../styles/keyline.md) rule.
+
+
+## Syntax
+
+| Value    | Description                |
+| -------- | -------------------------- |
+| `none`   | No line (disable keyline). |
+| `thin`   | A thin line.               |
+| `heavy`  | A heavy (thicker) line.    |
+| `double` | A double line.             |
+
+## Examples
+
+### CSS
+
+```sass
+Vertical {
+    keyline: thin green;
+}
+```
+
+### Python
+
+```py
+# A tuple of <keyline> and color
+widget.styles.keyline = ("thin", "green")
+```

docs/examples/styles/keyline.py

@@ -0,0 +1,19 @@
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.widgets import Placeholder
+
+
+class KeylineApp(App):
+    CSS_PATH = "keyline.tcss"
+
+    def compose(self) -> ComposeResult:
+        with Grid():
+            yield Placeholder(id="foo")
+            yield Placeholder(id="bar")
+            yield Placeholder()
+            yield Placeholder(classes="hidden")
+            yield Placeholder(id="baz")
+
+
+if __name__ == "__main__":
+    KeylineApp().run()

docs/examples/styles/keyline.tcss

@@ -0,0 +1,21 @@
+Grid {
+    grid-size: 3 3;
+    grid-gutter: 1;
+    padding: 2 3;
+    keyline: heavy green;
+}
+Placeholder {
+    height: 1fr;      
+}
+hidden {
+    visibility: hidden;
+} 
+#foo {
+    column-span: 2;
+}
+#bar {
+    row-span: 2;        
+}
+#baz {
+    column-span:3;
+}

docs/examples/styles/keyline_horizontal.py

@@ -0,0 +1,18 @@
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Placeholder
+
+
+class KeylineApp(App):
+    CSS_PATH = "keyline_horizontal.tcss"
+
+    def compose(self) -> ComposeResult:
+        with Horizontal():
+            yield Placeholder()
+            yield Placeholder()
+            yield Placeholder()
+
+
+if __name__ == "__main__":
+    app = KeylineApp()
+    app.run()

docs/examples/styles/keyline_horizontal.tcss

@@ -0,0 +1,8 @@
+Placeholder {
+    margin: 1;
+    width: 1fr;
+}
+
+Horizontal {
+    keyline: thin $secondary;
+}

docs/styles/keyline.md

@@ -0,0 +1,83 @@
+# Keyline
+
+The `keyline` style is applied to a container and will draw lines around child widgets.
+
+A keyline is superficially like the [border](./border.md) rule, but rather than draw inside the widget, a keyline is drawn outside of the widget's border. Additionally, unlike `border`, keylines can overlap and cross to create dividing lines between widgets.
+
+Because keylines are drawn in the widget's margin, you will need to apply the [margin](./margin.md) or [grid-gutter](./grid/grid_gutter.md) rule to see the effect.
+
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+keyline: [<a href="../../css_types/keyline">&lt;keyline&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+## Examples
+
+### Horizontal Keyline
+
+The following examples shows a simple horizontal layout with a thin keyline.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/keyline_horizontal.py"}
+    ```
+
+=== "keyline.py"
+
+    ```python
+    --8<-- "docs/examples/styles/keyline_horizontal.py"
+    ```
+
+=== "keyline.tcss"
+
+    ```sass
+    --8<-- "docs/examples/styles/keyline_horizontal.tcss"
+    ```
+
+
+
+### Grid keyline
+
+The following examples shows a grid layout with a *heavy* keyline.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/keyline.py"}
+    ```
+
+=== "keyline.py"
+
+    ```python
+    --8<-- "docs/examples/styles/keyline.py"
+    ```
+
+=== "keyline.tcss"
+
+    ```sass 
+    --8<-- "docs/examples/styles/keyline.tcss"
+    ```
+
+
+## CSS
+
+```sass
+/* Set a thin green keyline */
+/* Note: Must be set on a container or a widget with a layout. */
+keyline: thin green;
+```
+
+## Python
+
+You can set a keyline in Python with a tuple of type and color:
+
+```python
+widget.styles.keyline = ("thin", "green")
+```
+
+
+## See also
+
+ - [`border`](./border.md) to add a border around a widget.

mkdocs-nav.yml

@@ -32,6 +32,7 @@ nav:
           - "css_types/color.md"
           - "css_types/horizontal.md"
           - "css_types/integer.md"
+          - "css_types/keyline.md"
           - "css_types/name.md"
           - "css_types/number.md"
           - "css_types/overflow.md"
@@ -83,6 +84,7 @@ nav:
           - "styles/display.md"
           - "styles/dock.md"
           - "styles/index.md"
+          - "styles/keyline.md"
           - Grid:
               - "styles/grid/index.md"
               - "styles/grid/column_span.md"