Border colour percentage (#1954)

* Allow setting an additional alpha on a border

See #1863.

* Update the ChangeLog

* Add snapshot tests for the border alpha value

* Extend the border snapshot tests

While this doesn't test *every* permutation, it covers enough bases that if
something were to change it should catch it.

* Tweak a typo in the border style examples

* Add border transparency percentage to the border docs

* Add a CSS example for using border transparency

* Add Color.multiply_alpha

* Update the CHANGELOG

* Multiply the alpha on a colour rather than replace it

As requested in
https://github.com/Textualize/textual/pull/1954#pullrequestreview-1328170386

(actually required while talking in person with Will, but noted in the
above)

* Multiply the alpha on a border colour rather than replace it

As requested in
https://github.com/Textualize/textual/pull/1954#pullrequestreview-1328170386

(actually requested while talking in person with Will, but noted in the
above)

tests/snapshot_tests/snapshot_apps/border_alpha.py

@@ -0,0 +1,43 @@
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.widget import Widget
+
+class BorderAlphaApp(App[None]):
+
+    CSS = """
+    Grid {
+        height: 100%;
+        width: 100%;
+        grid-size: 2 2;
+    }
+
+    #b00 { border: 0%; }
+    #b01 { border: 33%; }
+    #b02 { border: 66%; }
+    #b03 { border: 100%; }
+
+    #b10 { border: solid 0%; }
+    #b11 { border: dashed 33%; }
+    #b12 { border: round 66%; }
+    #b13 { border: ascii 100%; }
+
+    #b20 { border: 0% red; }
+    #b21 { border: 33% orange; }
+    #b22 { border: 66% green; }
+    #b23 { border: 100% blue; }
+
+    #b30 { border: solid 0% red; }
+    #b31 { border: dashed 33% orange; }
+    #b32 { border: round 66% green; }
+    #b33 { border: ascii 100% blue; }
+    """
+
+    def compose( self ) -> ComposeResult:
+        with Grid():
+            for outer in range(4):
+                with Grid():
+                    for inner in range(4):
+                        yield Widget(id=f"b{outer}{inner}")
+
+if __name__ == "__main__":
+    BorderAlphaApp().run()

tests/snapshot_tests/test_snapshots.py

@@ -240,6 +240,11 @@ def test_label_widths(snap_compare):
     assert snap_compare(SNAPSHOT_APPS_DIR / "label_widths.py")
 
 
+def test_border_alpha(snap_compare):
+    """Test setting a border alpha."""
+    assert snap_compare(SNAPSHOT_APPS_DIR / "border_alpha.py")
+
+
 def test_auto_width_input(snap_compare):
     assert snap_compare(
         SNAPSHOT_APPS_DIR / "auto_width_input.py", press=["tab", *"Hello"]